feature

name	feature
description	Use when implementing a new feature — orchestrates the full chain brainstorm → architect/plan → implement → test → review → verify → docs. Triggers on phrases like "implement feature", "add feature", "build feature", "новая фича", "сделай фичу", or the /feature slash command.

Feature Development Chain

End-to-end orchestration for adding a new feature. Each phase has explicit gates — do not skip a gate without a written reason in the TodoWrite list.

Core principle: consistency over novelty. Follow existing patterns from CLAUDE.md and .claude/rules/*.md. Only deviate with a stated rationale.

Mandatory background reads

If you have not already read them this session:

• Root CLAUDE.md — project context, architecture, gotchas, post-change checklist
• Relevant files in .claude/rules/ — depending on what the feature touches (tests, migrations, frontend layering, messaging, board tracking, doc maintenance)
• Per-module / per-service CLAUDE.md for the affected area, if your project organises docs that way

TodoWrite scaffold

Open the chain by writing this todo list (skip phases only with explicit user permission, mark them as cancelled not completed):

1. Phase 0 — Issue tracking (find or create in board, move to In Progress)
2. Phase 0.5 — Success criterion (one verifiable line — see below)
3. Phase 1 — Brainstorm requirements
4. Phase 2 — Architect / write plan
5. Phase 3 — Implement backend (if applicable)
6. Phase 4 — Implement frontend (if applicable)
7. Phase 5 — Write tests
8. Phase 6 — Code review (code-reviewer subagent)
9. Phase 7 — Security review (if auth / new endpoint / untrusted input / SQL)
10. Phase 8 — Verify (build + test + manual smoke) — gate against Phase 0.5 criterion
11. Phase 9 — Update docs (CLAUDE.md, doc-maintenance rules)
12. Phase 10 — Close issue / link PR

Phase 0 — Issue tracking

Per .claude/rules/board-tracking.md (or your project's tracker rule):

1. Search existing issues by 3-5 keywords. If a relevant issue exists — reuse it (don't dedupe by creating a new one).
2. If none — create one per your project's tracker conventions (labels, assignee, priority defaults).
3. Move to In Progress (or equivalent status).
4. Note the issue identifier — it goes into commit messages and the PR description (Closes #N / Refs #N).

Skip Phase 0 only if the user said "do it without an issue" or the change is one-line (typo / copy / style). In both cases mark Phase 0 cancelled with reason.

Phase 0.5 — Success criterion (verifiable, one line)

Before any brainstorm / architect / code, write one observable check that proves the feature works. Drop it into the issue description (under ## Success criterion) and quote it verbatim in the TodoWrite todo. Karpathy:

"Execution is only as good as the goal and the verification you give it. Ambition without verification is just a wish."

Format: a single sentence with an explicit assertion — endpoint + expected response, UI action + visible result, SQL row count, log line, file existence. Always testable in <30 seconds at Phase 8.

❌ Weak (re-states the task)	✅ Strong (verifiable check)
"implement materials reuse"	POST /items/{id}/reuse → 200, response includes new itemId, GET /items/{newId} shows source_id == original.
"add export endpoint"	GET /reports/{id}/export.csv → valid CSV; opens in Excel; every row from the source query is visible in the output.
"fix drag-and-drop reordering"	Drag item from List A to List B → toast 'moved', refresh page, item appears in List B only, sort_key correctly placed between siblings.
"make subscriber notifications work"	Publish entity in feed Y where user U is subscribed. Within 5s of publish: row in notifications.inbox exists for U; SSE event delivered if connected.

Hard rules:

• One criterion, not a list. Multi-faceted features split into separate issues, one criterion each.
• Observable from outside the code. "Method X returns Result.Success" is internal. "Endpoint returns 200" is observable.
• Specific values, not properties. Not "returns an enrollment" — "response.enrollment.status == 'Active' and DB has matching row".
• Use real test data. Reference IDs / DTOs that exist in seed so Phase 8 can actually run the check.

If the criterion cannot be written in one sentence, the feature is under-specified — go back to the user before Phase 1. Don't proceed with a vague goal; you'll land in Phase 8 unable to claim it works.

Skip Phase 0.5 only for one-line copy / typo / styling fixes (same exemption as Phase 0).

Phase 1 — Brainstorm

Trigger superpowers:brainstorming if the task is non-trivial (more than one file, new endpoint, new entity, new event, schema change, or any cross-module touch).

Skip rules:

• User memory says brainstorm-skip is OK for experimental tasks. If user wrote "пропусти brainstorm" / "skip brainstorm" / "go straight to code" — skip and mark Phase 1 cancelled.
• For one-line bug-fix-shaped features (single field rename, copy change), skip brainstorm.

Output: short bullet list of requirements + answered open questions.

Phase 2 — Architect / Plan

Use the architect subagent (if your project has one) for design, OR superpowers:writing-plans for an executable plan. For multi-module or schema-touching features, do BOTH.

The plan MUST address whichever of these apply to the feature:

a) Access control (any user-facing endpoint that returns or mutates data) — see content-access skill for the three-tier pattern (permission / ownership / entitlement). Decide for list endpoints: metadata-only vs content-returning (the latter must filter in SQL).

b) Messaging changes (new exchange / routing key / consumer) — apply the three-spot rule from doc-maintenance.md: per-service doc + project-wide messaging table + conventions doc updated in the same change.

c) Migration plan (schema change) — per db-migrations.md: new migration only, never edit existing ones; no concurrent index creation inside transactions; cross-schema FK guards.

d) Cross-module / cross-service contracts — list which contract packages need bumping and which HTTP clients in other services need updates. If a typed client has a cache decorator, both need updating (CI does not enforce this).

e) Frontend data flow — see frontend-architecture.md: layer per new file, public-API barrels, mutation hook naming, status types live in shared layer, no upward / cross-slice imports.

Phase 3 — Backend implementation

Follow project's existing patterns:

• Result/Error monad for every operation (no throw for business errors).
• Time-ordered UUIDs (UUIDv7 / Guid.CreateVersion7()) in production code.
• Aggregate roots / entities / value objects per your DDD pattern.
• Transactional outbox: every event publish must be paired with the explicit SaveChanges/commit that flushes it. See messaging-tests.md — a publish without flush silently drops the event.
• Tier 1 + Tier 2 + Tier 3 access checks from the plan wired into the endpoint.

If a new HTTP route is added, follow the existing route-registration pattern (trailing slash on collection routes if your gateway requires it).

Phase 4 — Frontend implementation

Follow frontend-architecture.md. Run the lint gate to catch layer violations.

Common gotchas (override with project specifics):

• All API URLs end with trailing slash if your gateway 301s otherwise (breaks CORS preflight).
• Use the project's central icon registry — don't import icons directly from a library if a registry exists.
• Use the project's class-name helper (cn() / clsx()).
• Forms: schema-driven validation (Zod / Yup), no value coercion at parse time.
• Server-state library (TanStack Query / SWR) for fetches; mutation hooks in features/{slice}/model/.
• Composite keys when a list is built from multiple data sources (avoid React key collisions).

Phase 5 — Tests

Invoke the integration-test-coverage skill for any new endpoint or handler.

Required test levels (from messaging-tests.md if applicable):

• L1 — handler logic via in-process invoke for any new event handler.
• L2 — endpoint publish via tracked activity for any endpoint that publishes an event. This is the test that catches a missing flush.
• L3 (real broker round-trip) — out of scope; brokers stubbed in tests.

Test infra rules from integration-tests.md:

• Test-only UUID generation (NewGuid() / uuid4()) is fine.
• If your new endpoint uses a new rate-limit policy, register it in the test factory — otherwise the endpoint will throw at test time.
• Use entitlement fakes (GrantAll() / DenyAll()) to simulate access state.

Frontend tests: skip unless explicitly requested or the feature has non-trivial UI logic.

Phase 6 — Code review

Invoke the code-reviewer subagent against the changed files. Pass it the file list. The reviewer checks against CLAUDE.md / .claude/rules/ conventions: Result/Error usage, FSD violations, missing entitlement checks, missing outbox flush, missing migration guards.

Address every blocker the reviewer raises. Document any "wontfix" with rationale in the todo item.

Phase 7 — Security review

Invoke security-reviewer if ANY of:

• New endpoint added (any HTTP verb, any service)
• Auth / OIDC / Identity touched
• Permission constants added or changed
• Raw SQL or untyped ORM query introduced
• File upload, signed URL, or external integration touched
• Anonymous endpoint added or AllowAnonymous widened

For domain-content endpoints, re-run the content-access skill checklist before declaring done.

Phase 8 — Verification

Invoke superpowers:verification-before-completion. The chain is NOT done until every box below is green. Use the full-dev-verification skill to run the full battery, or run them piecewise.

First box — Phase 0.5 success criterion. Re-read the criterion verbatim from the issue / TodoWrite. Run the exact check (curl, SQL, browser action) and observe the result. Paste the actual result into the final report. If the criterion does not pass — return to Phase 3/4. Do NOT mark the chain complete or weaken the criterion.

• Success criterion from Phase 0.5 — observed and passing. Quote the criterion. Paste the actual check output.

Backend:

• Build succeeds for the project / solution (dotnet build, cargo build, go build, npm run build)
• Tests for every touched module / service pass
• If migration added: migration runs cleanly against a fresh DB
• If event added: the L2 test assertion passes

Frontend (if touched):

• Lint clean (0 warnings, 0 errors)
• Build succeeds
• If unit tests touched: they pass

Browser smoke (golden path):

• Start the app per project conventions
• Walk the feature's golden path manually (Playwright MCP if available): navigate, perform the primary action, assert the visible result. Capture a snapshot.
• If feature is gated, also test the lock state (anonymous / unenrolled user).

If anything is red, return to the relevant phase. Do NOT mark the chain complete with red boxes.

Phase 9 — Documentation

Apply doc-maintenance.md three-spot rule for messaging changes. Independently:

• Per-module / per-service CLAUDE.md updated if domain model / messaging / gotchas changed
• Root CLAUDE.md updated if architecture / authorization model / cross-module patterns changed
• If three-spot triggered: confirm all three files updated in the same change set
• If a new gotcha was discovered during implementation, add it to the relevant CLAUDE.md "Known Gotchas" section

Do NOT create freestanding .md design / summary / changelog files in the repo unless the user asked for one. Update existing CLAUDE.md only.

Phase 10 — Close issue / link PR

• If PR was opened: ensure description has Closes #N so merge auto-closes the issue. Move issue to In Review (or equivalent).
• If commit went straight to default branch: close manually and add a note linking the commit SHA.
• If feature was scoped down or split — leave the parent issue open with a comment listing follow-up issues, close only what's actually done.

Final report

Report to the user (caveman mode by default — terse, no emoji, Russian if user is using Russian):

• Files added / modified (absolute paths)
• Endpoints added (route + verb + auth)
• New events / migrations / cross-service contract bumps
• Test counts: L1 / L2 / unit
• Verification results (which boxes green / red)
• Any deferred work (gotchas, follow-ups) — mention only, do NOT silently fix unrelated code