<!-- AUTO-GENERATED FROM ai-tools/shared-prompts/. DO NOT EDIT DIRECTLY. -->
<!-- To change: edit _header-windsurf.md or standards.md, then run scripts/build-ai-configs.sh -->

<!-- Tool: Windsurf. Output path: .windsurfrules -->

# .windsurfrules — Project rules for Windsurf

You are an expert AI pair-programmer working in this repo. You MUST follow the
project standards below. When in doubt, prefer the conventions described in
`03-Development/standards/`.

<!-- standards.md — shared body included into every AI tool config. -->
<!-- Source of truth. Edit this file (and per-tool _header-*.md) only. -->

## ⚡ Subagent priority — read this first

This repo has 11 specialist subagents in `.claude/agents/`. Files include:

- **Phase 1**: `pm-agent.md`
- **Phase 2 architecture**: `architect-agent.md`
- **Phase 2 UI/UX**: `ux-designer.md`
- **Phase 3 task stages**: `test-author.md` (write-tests), `developer-agent.md` (write-code), `code-reviewer.md` (review)
- **Phase 4 E2E**: `qa-engineer.md`
- **Phase 5 deploy & monitor**: `sre-agent.md`
- **Cross-cutting**: `security-reviewer.md`, `doc-keeper.md`, `clarification-triager.md`, `orchestrator.md`

**When the user says "use the X subagent ..." or runs `/agents X`, you MUST honour the named subagent and not delegate to plugin skills (e.g. brainstorming).** The subagent files in `.claude/agents/` are this repo's authoritative role specs. If you have a plugin skill whose description overlaps with what the user asked, defer to the named subagent.

## ⚡ Default behaviour when the user shares a project idea

If the user's first substantive message in this repo describes a **project idea / requirement / what they want to build** ("I want to build", "let's start a project", "yêu cầu là...", "tôi muốn build", a pasted brief, etc.) — and `automation/state.json` shows `prd-drafted` is **NOT done** — then **automatically**:

1. Adopt the **`pm-agent`** role (read `agents/phase-1-pm.md`).
2. Read `01-Planning/templates/01-PRD.md` for structure.
3. Read `automation/rules.json` → find item `prd-drafted` → know what evidence is required.
4. Save the user's raw idea to `01-Planning/IDEA.md`.
5. Write the actual filled-in PRD to **`01-Planning/01-PRD.md`** (NOT into `templates/`), replacing all `{{PLACEHOLDERS}}`. Quantify NFRs (p95 / p99 / RTO / RPO / uptime%). Leave at most 5 placeholders for genuinely unknown values, marked `{{TBD: <reason>}}`.
6. **Append the verify marker** at the bottom: `<!-- sdlc:verified-by: <user-name> <iso-date> -->`. The user may overwrite later via `sdlc verify prd-drafted --name=<who>`.
7. Briefly tell the user what you wrote and what's next: `sdlc scan --print`, `sdlc next`.
8. **Stop**. Do not auto-progress to user stories / requirements unless the user asks. Phase 1 has more items (`user-stories`, `nfr-targets`, `stakeholder-map`, `risks-identified`); the user picks pace.

**STOP triggers** (write `automation/clarifications/<NNN>-...md` with `STATUS: open` and halt):
- 🔍 Ambiguity: idea too vague to fill required PRD sections
- ⚔️ Conflict: user gave conflicting constraints
- 🛑 High-risk path: idea touches auth/crypto/payment/secrets/migrations and needs explicit direction

---

## SDLC framework — 5-phase model

This repo follows a 5-phase SDLC. Every change should advance one of the Definition-of-Done items tracked in `automation/state.json`. Run `sdlc scan --print` to see current state.

### Phases (high-level)

1. **Planning** (`01-Planning/`) — PRD, user stories (G/W/T), quantified NFRs, stakeholder map + RACI, risks. Per-artifact verify required.
2. **Design** (`02-Design/`) — two sub-tracks:
   - 🏛️ **Architecture**: C4, API spec (OpenAPI), DB schema, ADRs, STRIDE threat model
   - 🎨 **UI/UX**: UI spec, wireframes, design system, accessibility (WCAG)
3. **Development** (`03-Development/`) — two sub-tracks:
   - 🛠️ **Setup**: coding standards, git workflow, PR template, security checklist, AI tool configs, AI disclosure, TDD coverage (mostly green post-`sdlc init`)
   - ✅ **Tasks**: per-feature Kanban with sequential TDD strict (5 stages: pending → write-tests → write-code → review → done)
4. **E2E & Integration Testing** (`04-Testing-Deploy/`) — test plan, E2E suite, integration, smoke, regression, load tests
5. **Deploy & Monitor** (`04-Testing-Deploy/`) — CI/CD, deploy runbook, SLOs, incident response, observability dashboard

### Per-artifact verify (Phase 1, 2, 4)

Each artifact has a two-state model: `drafted` + `verified`. Both must be true for the item to be `done`.

To verify, append the marker at the bottom of the file (or run `sdlc verify <item-id>`):

```markdown
<!-- sdlc:verified-by: <name> <iso-date> -->
```

Three visual states on the dashboard: ⚪ pending → 🟡 drafted, awaiting verify → ✅ verified.

### Phase 3 task lifecycle (sequential TDD strict)

Tasks live in `automation/tasks/<id>.yaml`. Each task progresses through 5 stages. Stage detection is automatic (filesystem + `gh pr view`):

| Stage | Detection | Subagent invoked |
|-------|-----------|------------------|
| `pending` | no code, no tests | `test-author` |
| `write-tests` | tests exist, no code (or tests < code, regression) | `developer-agent` |
| `write-code` | tests ≥ code, no PR | `code-reviewer` (or `security-reviewer` if sensitive area: auth/crypto/payment/secrets/migrations) |
| `review` | PR open | (waits for human merge) |
| `done` | PR merged | (terminal) |

Each subagent runs in a **fresh context** — no memory leakage between stages. Strict TDD: tests come first, then code, then review.

When acting on a Phase 3 task, follow your stage's mandate strictly:
- `test-author` writes tests only — does not write production code
- `developer-agent` writes code that makes tests pass — does not modify tests
- `code-reviewer` does not modify code — leaves findings under `automation/reviews/<task-id>-<ts>.md`

Bootstrap tasks from user stories: `sdlc tasks bootstrap`. Manual task: `sdlc tasks new <id>`.

### Standards live in `03-Development/standards/`

- `coding-standards.md`
- `git-workflow.md`
- `error-handling.md`
- `security-checklist.md`

Read them before writing code.

### Project metadata: `project.yaml`

When present, the engine reads:

- `schema_version: 2` (v2 phase model)
- `tier` (1=critical / 2=standard / 3=experiment) — drives DoD strictness
- `phase_target` (1..5) — focus phase
- `stack` — node / python / go (auto-detected)
- `owners` — sponsor, eng_lead, security, sre, qa (per-tier requirements)
- `legacy_code_globs` — paths excluded from TDD coverage (for retrofit projects)
- `e2e_glob`, `integration_glob` — Phase 4 detection overrides
- `observability` — `dashboard_url`, `on_call_runbook` (tier 1)

The engine fails `owners-defined` rule when required owners for the project's tier are missing.

### Autonomous loop rules

When operating without a human in the loop, follow `automation/AGENT-LOOP.md`. Stop and write a clarification file under `automation/clarifications/` when:

- Information is ambiguous or missing
- Two sources conflict
- A gate (sign-off) is required
- The task touches a high-risk path: auth, crypto, payment, secrets, database migrations, webhooks

Resolve a clarification: edit the file, change `STATUS: open` → `STATUS: resolved`. Approve a gate: write `automation/signoffs/<gate-id>.yaml` with `approved: true`.

### AI disclosure

Every PR must include the AI tool disclosure section from `03-Development/templates/PR-Template.md`. Do not omit it.

### Adopting on an existing running project

For a project that already has code, designs, or runbooks, run `sdlc adopt`. The wizard scans for existing assets (`docs/PRD.md`, `docs/ARCHITECTURE.md`, runbooks, SLO docs, CI workflows, source + test files), creates symlinks into the canonical SDLC paths, and auto-verifies them with the marker `imported-from-existing`. Idempotent and non-destructive.

For Phase 3 development on retrofits, set `legacy_code_globs: ["src/**"]` in `project.yaml` so existing code is grandfathered (no TDD enforcement); only new tasks under `automation/tasks/` go through the full TDD cycle.

### CLI — recommended commands

```bash
# Daily flow
sdlc resume                           # "where am I?" — phase, last activity, next action
sdlc next                             # paste-ready prompt for the next pending DoD item
sdlc scan --print                     # progress summary
sdlc verify <item-id>                 # mark a Phase 1/2/4 artifact verified

# Tasks (Phase 3)
sdlc tasks bootstrap                  # auto-create tasks from user stories
sdlc tasks list                       # tasks with current stage
sdlc tasks new <id>                   # manual task creation

# Adjustments
sdlc replan                           # mark items dirty after a major change

# Engine + dashboard
sdlc scan --watch                     # background scanner with notifications
sdlc dashboard                        # serve UI on localhost
```

### Logging your run (optional)

When you start working on an SDLC item, append a `start` entry to the activity log; when you finish, append `done` or `fail`:

```bash
# at the start
SDLC_TOOL=<your-tool> sdlc agent-log start <agent-name> <item-id>
# work...
# at the end
sdlc agent-log done <agent-name> <item-id> --summary="<one-line>"
# or on failure
sdlc agent-log fail <agent-name> <item-id> --summary="<error>"
```

The log is local-only, gitignored, capped at 50 entries. Failing to call the wrapper breaks nothing.

### Surfacing STOP triggers to GitHub

When you raise a clarification or gate-signoff placeholder, optionally file it on GitHub:

```bash
sdlc gh-issue --clarification automation/clarifications/<NNN>-...md
sdlc gh-issue --gate <gate-id>
```

Both wrappers are idempotent (skip on existing `issue_url:`) and exit 0 when `gh` is unavailable. For Phase 3 task review, open a Draft PR: `sdlc gh-pr`.
