triples-agentic 2.4.0

package/src/hooks/README.md

@@ -0,0 +1,102 @@
+# hooks/
+
+Safety guardrail definitions — the source of truth for dangerous-command blocking across all platforms.
+
+The installer reads these files and generates platform-specific hook configs. Edit here, reinstall, and every platform gets the update.
+
+---
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `dangerous-commands.json` | Per-platform executable hook configs (Claude Code, Codex, Windsurf) |
+| `dangerous-commands.md` | Text-based safety rules for platforms without executable hooks (Cursor, Copilot) |
+
+---
+
+## `*.json` — Executable hook configs
+
+Each JSON file describes one safety rule and carries per-platform configurations under a `platforms` key.
+
+```json
+{
+  "name": "dangerous-commands",
+  "description": "Block dangerous shell commands before execution",
+  "platforms": {
+    "claude": {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hooks": [{ "type": "command", "command": "...", "statusMessage": "..." }]
+    },
+    "codex": {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hooks": [{ "type": "command", "command": "...", "statusMessage": "..." }]
+    },
+    "windsurf": {
+      "event": "pre_run_command",
+      "command": "...",
+      "show_output": true
+    }
+  }
+}
+```
+
+### Platform differences
+
+| Platform | Event name | Input key | Block mechanism |
+|---|---|---|---|
+| Claude Code | `PreToolUse` | `tool_input.command` | stdout JSON `{"decision":"block"}` |
+| OpenAI Codex | `PreToolUse` | `tool_input.command` | stdout JSON `{"decision":"block"}` (same engine) |
+| Windsurf | `pre_run_command` | `tool_info.command_line` | exit code `2` |
+
+All hooks receive the tool input as JSON on stdin and run as a bash command.
+
+### How the installer uses this
+
+- `platforms.claude` → merged into `.claude/settings.json` under `hooks.PreToolUse`
+- `platforms.codex` → appended to `.codex/config.toml` under `[[hooks.PreToolUse]]`
+- `platforms.windsurf` → merged into `.windsurf/hooks.json` under `hooks.pre_run_command`
+
+Reinstalling is idempotent — the installer removes the previous triples-agentic entry before writing the new one.
+
+---
+
+## `*.md` — Text-based safety rules
+
+Used for platforms that have no executable hook mechanism. The installer strips the frontmatter and injects the body as an always-applied rule.
+
+```markdown
+---
+name: dangerous-commands-safety
+description: Safety guardrails — never run dangerous commands without explicit user confirmation
+platform: all
+---
+
+## Safety Guardrails
+
+Never run these commands without explicit user confirmation:
+…
+```
+
+### How the installer uses this
+
+| Platform | Output |
+|---|---|
+| Cursor AI | `.cursor/rules/triples-safety.mdc` with `alwaysApply: true` |
+| GitHub Copilot | `.github/instructions/triples-safety.instructions.md` with `applyTo: "**"` |
+
+---
+
+## Adding a new safety rule
+
+1. Edit the pattern list in the `command` field of `dangerous-commands.json` (all three platform sections).
+2. Add the human-readable description to `dangerous-commands.md`.
+3. Reinstall: `npx triples-agentic`.
+
+## Adding a new platform
+
+1. Add a `"<platform>"` key under `platforms` in each `.json` hook file.
+2. Add a loader function and settings writer in `src/bin/setup.js`.
+3. Call the settings writer from the platform's `install*` function.

package/src/hooks/dangerous-commands.json

@@ -0,0 +1,33 @@
+{
+  "name": "dangerous-commands",
+  "description": "Block dangerous shell commands before execution",
+  "platforms": {
+    "claude": {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "cmd=$(jq -r '.tool_input.command // \"\"'); if echo \"$cmd\" | grep -qiE 'rm[[:space:]]+-rf|rm[[:space:]]+-fr|rm[[:space:]]+(-[a-z]*r[a-z]*[[:space:]]+-[a-z]*f|-[a-z]*f[a-z]*[[:space:]]+-[a-z]*r)|git[[:space:]]+reset[[:space:]]+--hard|git[[:space:]]+push[[:space:]]+(.*--force|-f[[:space:]])|git[[:space:]]+checkout[[:space:]]+--|git[[:space:]]+restore[[:space:]]+\\.|DROP[[:space:]]+(TABLE|DATABASE)|DELETE[[:space:]]+FROM[[:space:]]+[a-zA-Z_]+[[:space:]]*;|fastlane[[:space:]]+(deliver|supply)|gradlew[[:space:]]+.*publishBundle|xcrun[[:space:]]+altool|npm[[:space:]]+publish[[:space:]]|npx[[:space:]]+.*publish[[:space:]]'; then printf '{\"decision\":\"block\",\"reason\":\"Blocked dangerous command — review and run manually if intentional.\"}'; fi",
+          "statusMessage": "Checking for dangerous commands..."
+        }
+      ]
+    },
+    "codex": {
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "cmd=$(jq -r '.tool_input.command // \"\"'); if echo \"$cmd\" | grep -qiE 'rm[[:space:]]+-rf|rm[[:space:]]+-fr|rm[[:space:]]+(-[a-z]*r[a-z]*[[:space:]]+-[a-z]*f|-[a-z]*f[a-z]*[[:space:]]+-[a-z]*r)|git[[:space:]]+reset[[:space:]]+--hard|git[[:space:]]+push[[:space:]]+(.*--force|-f[[:space:]])|git[[:space:]]+checkout[[:space:]]+--|git[[:space:]]+restore[[:space:]]+\\.|DROP[[:space:]]+(TABLE|DATABASE)|DELETE[[:space:]]+FROM[[:space:]]+[a-zA-Z_]+[[:space:]]*;|fastlane[[:space:]]+(deliver|supply)|gradlew[[:space:]]+.*publishBundle|xcrun[[:space:]]+altool|npm[[:space:]]+publish[[:space:]]|npx[[:space:]]+.*publish[[:space:]]'; then printf '{\"decision\":\"block\",\"reason\":\"Blocked dangerous command — review and run manually if intentional.\"}'; fi",
+          "statusMessage": "Checking for dangerous commands..."
+        }
+      ]
+    },
+    "windsurf": {
+      "event": "pre_run_command",
+      "command": "cmd=$(jq -r '.tool_info.command_line // \"\"' 2>/dev/null || echo \"\"); if echo \"$cmd\" | grep -qiE 'rm[[:space:]]+-rf|rm[[:space:]]+-fr|rm[[:space:]]+(-[a-z]*r[a-z]*[[:space:]]+-[a-z]*f|-[a-z]*f[a-z]*[[:space:]]+-[a-z]*r)|git[[:space:]]+reset[[:space:]]+--hard|git[[:space:]]+push[[:space:]]+(.*--force|-f[[:space:]])|git[[:space:]]+checkout[[:space:]]+--|git[[:space:]]+restore[[:space:]]+\\.|DROP[[:space:]]+(TABLE|DATABASE)|DELETE[[:space:]]+FROM[[:space:]]+[a-zA-Z_]+[[:space:]]*;|fastlane[[:space:]]+(deliver|supply)|gradlew[[:space:]]+.*publishBundle|xcrun[[:space:]]+altool|npm[[:space:]]+publish[[:space:]]|npx[[:space:]]+.*publish[[:space:]]'; then printf 'Blocked dangerous command — review and run manually if intentional.\\n' >&2; exit 2; fi",
+      "show_output": true
+    }
+  }
+}

package/src/hooks/dangerous-commands.md

@@ -0,0 +1,18 @@
+---
+name: dangerous-commands-safety
+description: Safety guardrails — never run dangerous commands without explicit user confirmation
+platform: all
+---
+
+## Safety Guardrails
+
+Never run these commands without explicit user confirmation:
+
+- **Filesystem**: `rm -rf`, `rm -fr`, any recursive force delete
+- **Git destructive**: `git reset --hard`, `git checkout --`, `git restore .`
+- **Git push force**: `git push --force`, `git push -f`
+- **SQL destructive**: `DROP TABLE`, `DROP DATABASE`, `DELETE FROM <table>;`
+- **Store publish**: `fastlane deliver`, `fastlane supply`, `gradlew publishBundle`, `xcrun altool`
+- **Package publish**: `npm publish`, `npx ... publish`
+
+Stop and ask the user for explicit confirmation before running any of the above.

package/src/knowledge/README.md

@@ -0,0 +1,129 @@
+# knowledge/
+
+Domain expertise loaded by agents at runtime. Pure reference `.md` files — no trigger logic, no skills framework.
+
+Agents declare which files to load via `<!-- knowledge: ... -->` metadata in their agent definition. The AI reads and applies these files as context when it activates.
+
+---
+
+## File format
+
+Every knowledge file has YAML frontmatter followed by markdown content:
+
+```markdown
+---
+name: api-design
+description: REST and GraphQL API design conventions — URL structure, versioning, pagination, filtering, and documentation
+---
+
+# API Design
+
+## REST URL Conventions
+…
+```
+
+| Field | Purpose |
+|---|---|
+| `name` | Slug used as the skill name when installed to Claude Code |
+| `description` | One-line summary shown in the install banner and used as the skill trigger description |
+
+The content is plain markdown — headings, bullet lists, code blocks. Write it as a reference document, not a tutorial.
+
+---
+
+## Directory structure
+
+```
+knowledge/
+├── general/           Coding principles — loaded by all developer agents
+│   ├── dry.md         Don't Repeat Yourself
+│   ├── kiss.md        Keep It Simple
+│   ├── yagni.md       You Aren't Gonna Need It
+│   ├── solid.md       SOLID principles
+│   ├── slap.md        Single Level of Abstraction
+│   ├── tdd.md         Test-Driven Development
+│   ├── fail-fast.md   Validate at boundaries, surface errors early
+│   ├── least-surprise.md  Code behaves as readers expect
+│   ├── boy-scout-rule.md  Leave code cleaner than you found it
+│   └── composition-over-inheritance.md
+│
+├── planning/          Loaded by SeoYeon, JiWoo, YooYeon, NaKyoung
+│   ├── orchestration.md         Workflow sequencing, delegation, escalation
+│   ├── prd-writing.md           PRD structure, writing standards, anti-patterns
+│   ├── prd-quality-gates.md     PRD review checklist
+│   ├── product-principles.md    PM principles, prioritization frameworks
+│   ├── product-prioritization.md
+│   ├── rfc-writing.md           RFC structure, ADR format, anti-patterns
+│   ├── rfc-quality-gates.md     RFC review checklist
+│   ├── architecture-patterns.md System design, database selection, scalability
+│   ├── architecture-database.md Database design and selection criteria
+│   ├── architecture-security.md Security fundamentals for system design
+│   ├── task-decomposition.md    Task hierarchy, story mapping, readiness checklist
+│   ├── task-readiness.md        Task readiness criteria
+│   └── estimation.md            Fibonacci points, time estimation, planning poker
+│
+├── web/
+│   ├── frontend/      Loaded by YuBin
+│   │   ├── frontend-components.md  React/Vue/Angular patterns, component design
+│   │   ├── frontend-state.md       State management patterns
+│   │   ├── frontend-performance.md Bundle size, rendering, lazy loading
+│   │   ├── web-accessibility.md    WCAG 2.1 AA, semantic HTML, ARIA
+│   │   ├── web-performance.md      LCP, CLS, Core Web Vitals
+│   │   └── web-security.md         CSP, XSS prevention, secure headers
+│   └── backend/       Loaded by Kaede (api-design.md also loaded by Kotone)
+│       ├── backend-structure.md    Project layout, layered architecture
+│       ├── backend-security.md     Input validation, parameterized queries, secrets
+│       ├── api-design.md           REST/GraphQL conventions, versioning, pagination
+│       └── api-security.md         Auth, rate limiting, OWASP API top 10
+│
+├── mobile/
+│   ├── android/       Loaded by YeonJi
+│   │   ├── android-architecture.md  MVVM, Compose, Hilt, Navigation, Material 3
+│   │   ├── android-platform.md      Play Store, permissions, lifecycle
+│   │   ├── kotlin-core.md           Null safety, sealed classes, extension functions
+│   │   └── kotlin-concurrency.md   Coroutines, Flow, structured concurrency
+│   ├── ios/           Loaded by SoHyun
+│   │   ├── ios-architecture.md      SwiftUI, MVVM, NavigationStack, Apple HIG
+│   │   ├── ios-platform.md          App Store, privacy manifest, safe areas
+│   │   ├── swift-core.md            Optionals, value types, async/await, protocols
+│   │   └── swift-concurrency.md    actors, async/await, Task, structured concurrency
+│   └── flutter/       Loaded by Kotone
+│       ├── flutter-architecture.md  Riverpod, GoRouter, Material 3, widget design
+│       ├── flutter-platform.md      Play Store + App Store, platform channels
+│       ├── dart-core.md             Null safety, collections, classes, mixins
+│       └── dart-async.md            async/await, Future, Stream, Isolate
+│
+└── quality/           Loaded by Lynn and ShiOn
+    ├── testing-strategy.md    Testing pyramid, shift-left, anti-patterns
+    ├── testing-types.md       Unit, integration, E2E, exploratory definitions
+    ├── test-case-writing.md   Test case structure, priority levels, quality gates
+    ├── test-case-quality.md   Quality checklist for test case review
+    ├── qa-execution.md        Execution process, bug report format, go/no-go criteria
+    └── qa-reporting.md        QA report structure, metrics, defect classification
+```
+
+---
+
+## How knowledge gets installed
+
+The installer copies each knowledge file to the target platform directory alongside the agent files:
+
+| Platform | Installed path |
+|---|---|
+| Claude Code | `.claude/skills/knowledge/<group>/<file>.md` (existing frontmatter kept) |
+| Cursor AI | `.cursor/rules/knowledge/<group>/<file>.mdc` (frontmatter rewritten for Cursor) |
+| GitHub Copilot | `.github/instructions/knowledge/<group>/<file>.instructions.md` |
+| OpenAI Codex | Inline section in `AGENTS.md` (frontmatter stripped) |
+| Windsurf | Inline section in `.windsurfrules` (frontmatter stripped) |
+
+---
+
+## Adding a knowledge file
+
+1. Create a `.md` file in the appropriate subdirectory.
+2. Add frontmatter with `name` and `description`.
+3. Write the content as a reference document.
+4. Reference it in the agent's `<!-- knowledge: ... -->` metadata and add a line to its `## Knowledge` section.
+5. Reinstall: `npx triples-agentic`.
+
+Knowledge files are **read-only reference** — they describe what to know, not what to do. Procedural steps belong in agent `## Skills` sections.

package/src/knowledge/general/boy-scout-rule.md

@@ -0,0 +1,13 @@
+---
+name: boy-scout-rule
+description: Boy Scout Rule — leave the code cleaner than you found it through small, incremental improvements
+---
+
+# Boy Scout Rule
+
+Leave the code cleaner than you found it.
+
+- If you touch a file, fix the obvious issues nearby (rename a confusing variable, remove a dead comment)
+- Do not let this justify scope creep — small, incremental improvements only
+- Do not refactor code you do not understand yet
+- A codebase that improves slightly with every PR never needs a big rewrite

package/src/knowledge/general/composition-over-inheritance.md

@@ -0,0 +1,14 @@
+---
+name: composition-over-inheritance
+description: Favor composing behavior from small focused pieces over deep inheritance hierarchies
+---
+
+# Composition Over Inheritance
+
+Favor composing behavior from small, focused pieces over deep inheritance hierarchies.
+
+- Inheritance couples subclass to superclass implementation details
+- Composition lets you swap or combine behaviors at runtime
+- Prefer interfaces/protocols + composition when multiple behaviors are needed
+- Deep inheritance trees are hard to reason about — changes at the top ripple unpredictably
+- A class that inherits from more than one level of hierarchy is a warning sign

package/src/knowledge/general/dry.md

@@ -0,0 +1,14 @@
+---
+name: dry
+description: DRY (Don't Repeat Yourself) — every piece of knowledge must have a single, unambiguous representation in the system
+---
+
+# DRY — Don't Repeat Yourself
+
+Every piece of knowledge must have a single, unambiguous representation in the system.
+
+- Extract repeated logic into a named function, class, or module
+- Repeated data belongs in a constant or configuration, not scattered literals
+- Duplication of intent is worse than duplication of text — two functions that do the same thing but look different are the hardest to catch
+
+**When NOT to apply:** Premature abstraction to avoid three similar-looking lines produces worse code than the duplication. Wait for a third repetition before extracting. Deduplication that crosses wrong boundaries creates tight coupling.

package/src/knowledge/general/fail-fast.md

@@ -0,0 +1,13 @@
+---
+name: fail-fast
+description: Fail Fast — detect and surface errors as early and loudly as possible
+---
+
+# Fail Fast
+
+Detect and surface errors as early and loudly as possible.
+
+- Validate inputs at system boundaries, not deep inside business logic
+- Return or throw immediately on invalid state — don't carry partial state forward
+- Assertions and guards at function entry are cheaper than debugging corrupted state later
+- An error that surfaces at the point of cause is 10x easier to diagnose than one that surfaces two call frames later

package/src/knowledge/general/kiss.md

@@ -0,0 +1,15 @@
+---
+name: kiss
+description: KISS (Keep It Simple, Stupid) — the simplest solution that works is correct; complexity must justify itself
+---
+
+# KISS — Keep It Simple, Stupid
+
+The simplest solution that works is correct. Complexity must justify itself.
+
+- Prefer readable, obvious code over clever one-liners
+- Avoid over-engineering for hypothetical future requirements
+- If you need a comment to explain what the code does, the code is probably too complex
+- Fewer moving parts = fewer failure modes
+
+**Ask before adding complexity:** "Will this system actually need this in the next 3 months?" If no, don't build it.

package/src/knowledge/general/least-surprise.md

@@ -0,0 +1,13 @@
+---
+name: least-surprise
+description: Principle of Least Surprise — code should behave in the way a reader would expect
+---
+
+# Principle of Least Surprise
+
+Code should behave in the way a reader would expect.
+
+- Functions named `getUser` should not modify state
+- A method that returns a list should never return `null` — return an empty list
+- Avoid side effects in places where callers don't expect them (constructors, getters, equality checks)
+- Consistent naming conventions matter: if `save()` persists to DB everywhere, it should do so everywhere

package/src/knowledge/general/slap.md

@@ -0,0 +1,29 @@
+---
+name: slap
+description: SLAP (Single Level of Abstraction Principle) — each function should operate at a single level of abstraction
+---
+
+# SLAP — Single Level of Abstraction Principle
+
+Each function should operate at a single level of abstraction.
+
+```
+// Bad — mixes high-level orchestration with low-level detail
+function processOrder(order) {
+  validateOrder(order);
+  const sql = `INSERT INTO orders (id, total) VALUES (${order.id}, ${order.total})`;
+  db.execute(sql);
+  sendEmail(order.user.email, 'Order confirmed');
+}
+
+// Good — consistent abstraction level
+function processOrder(order) {
+  validateOrder(order);
+  saveOrder(order);
+  notifyUser(order);
+}
+```
+
+- If one line calls a named function and the next line contains raw SQL or DOM manipulation, the abstraction levels are mismatched
+- Extract lower-level details into well-named helpers to restore consistency
+- Consistent abstraction levels make a function readable top-to-bottom without context switches

package/src/knowledge/general/solid.md

@@ -0,0 +1,44 @@
+---
+name: solid
+description: SOLID principles for object-oriented design — SRP, OCP, LSP, ISP, DIP
+---
+
+# SOLID Principles (Object-Oriented Design)
+
+## S — Single Responsibility Principle
+A class (or module, or function) should have one reason to change.
+
+- A class that handles both business logic and database access has two reasons to change
+- Split responsibilities along the axis of change: what causes this to need updating?
+- Small, focused units are easier to test, reuse, and rename
+
+## O — Open/Closed Principle
+Open for extension, closed for modification.
+
+- Add new behavior by adding new code, not by editing existing code
+- Use polymorphism, strategy pattern, or composition to extend behavior
+- Modifying existing code risks breaking existing behavior; adding new code does not
+
+## L — Liskov Substitution Principle
+Subtypes must be substitutable for their base types without breaking the program.
+
+- If `class B extends A`, then anywhere `A` is used, `B` must work correctly
+- Violations: a subclass that throws on a method the base class supports, or returns a narrower result
+- If you find yourself overriding a method to do nothing or throw, the inheritance hierarchy is wrong
+
+## I — Interface Segregation Principle
+No client should be forced to depend on methods it does not use.
+
+- Prefer several small, focused interfaces over one large general-purpose interface
+- A class that implements a large interface but only needs 2 of 10 methods is a sign the interface should be split
+- Applies to function parameters too: pass only what the callee actually needs
+
+## D — Dependency Inversion Principle
+High-level modules should not depend on low-level modules. Both should depend on abstractions.
+
+- Business logic should not import a specific database library directly — it should depend on a repository interface
+- Makes high-level policy independent of implementation details
+- Enables swapping implementations (e.g., real DB vs. in-memory for tests) without changing business logic
+
+## When to apply SOLID
+SOLID is most valuable at module and service boundaries. Inside a small, private function, rigid SOLID application adds noise without benefit. Don't add abstractions until you have two concrete use cases.

package/src/knowledge/general/tdd.md

@@ -0,0 +1,76 @@
+---
+name: tdd
+description: Test-Driven Development (TDD) — write a failing test first, then write the minimum code to make it pass, then refactor
+---
+
+# TDD — Test-Driven Development
+
+Write a failing test before writing any production code. Let the test drive the design.
+
+## The Red-Green-Refactor Cycle
+
+1. **Red** — write a test that describes the desired behavior. Run it. It must fail.
+2. **Green** — write the minimum code to make the test pass. No more.
+3. **Refactor** — clean up the code without changing behavior. Tests stay green.
+
+Repeat for every new behavior.
+
+## Rules
+
+- Never write production code without a failing test that justifies it
+- Write only enough production code to make the current failing test pass
+- Never refactor while red — only clean up when tests are passing
+- One failing test at a time: don't write the next test until the current one is green
+
+## Why TDD produces better design
+
+- Forces you to think about the interface before the implementation
+- Code that is hard to test is a signal of tight coupling or unclear responsibilities — TDD surfaces this early
+- The test suite becomes a living specification of what the system does
+- Refactoring is safe when every behavior is covered — you move fast without breaking things
+
+## What a good TDD test looks like
+
+```
+// Arrange — set up the inputs and context
+// Act — call the unit under test
+// Assert — verify the outcome
+
+test('calculates order total with discount applied', () => {
+  const order = new Order([{ price: 100, qty: 2 }]);
+
+  const total = order.totalWithDiscount(0.1);
+
+  expect(total).toBe(180);
+});
+```
+
+- One concept per test
+- Test name describes the behavior, not the implementation ("returns 180" not "calls applyDiscount")
+- No logic in tests (no if/for) — tests should be trivially readable
+- Tests are isolated: no shared mutable state between tests
+
+## TDD scope
+
+| Level | What to TDD | Examples |
+|---|---|---|
+| Unit | Business logic, calculations, transformations | Services, utilities, domain models |
+| Integration | Interactions between components | Repository + DB, API handler + service |
+| E2E | Critical user flows | Login, checkout, core happy path |
+
+TDD is most valuable at the unit and integration levels. E2E tests are expensive to write first — write them after the feature is built to lock in the happy path.
+
+## When NOT to apply TDD strictly
+
+- **Exploratory / spike code** — when you don't yet know the shape of the solution, write the spike first, then delete it and TDD the real implementation
+- **UI layout and styling** — visual behavior is better verified by snapshot or manual review
+- **Third-party integrations** — write tests against your wrapper/adapter, not against the external API itself
+
+## TDD and refactoring
+
+The refactor step is not optional. Green tests without refactoring accumulates design debt. After each green:
+
+- Remove duplication (DRY)
+- Rename for clarity
+- Extract if a function is doing more than one thing (SRP)
+- The test suite must still be fully green after every change

package/src/knowledge/general/yagni.md

@@ -0,0 +1,12 @@
+---
+name: yagni
+description: YAGNI (You Aren't Gonna Need It) — do not implement something until it is actually required
+---
+
+# YAGNI — You Aren't Gonna Need It
+
+Do not implement something until it is actually required.
+
+- No speculative features, hooks for future use, or "just in case" parameters
+- Extension points and abstractions added before they are needed almost always get the shape wrong
+- Dead code is a maintenance liability — it still needs to be read, reasoned about, and updated

package/src/knowledge/mobile/android/android-architecture.md

@@ -0,0 +1,83 @@
+---
+name: android-architecture
+description: Android MVVM + Clean Architecture, Jetpack Compose patterns, Hilt DI, and Navigation Compose
+---
+
+# Android Architecture
+
+## Architecture Pattern: MVVM + Clean Architecture
+
+```
+UI Layer (Composable)
+    ↕ StateFlow / collect
+ViewModel (state holder, no Android dependencies)
+    ↕ suspend functions / Flow
+Repository (single data access layer)
+    ↕ API / Room / DataStore
+```
+
+## Jetpack Compose Rules
+
+- Composables are stateless by default — pass state down, events up
+- Use `remember` for UI-only ephemeral state (not business state)
+- Hoist state to the lowest common ancestor that needs it
+- Break large composables into smaller ones: if it doesn't fit on one screen, split it
+
+```kotlin
+// Correct: stateless composable + hoisted state in ViewModel
+@Composable
+fun LoginScreen(
+    uiState: LoginUiState,
+    onEmailChanged: (String) -> Unit,
+    onLoginClick: () -> Unit,
+) { ... }
+
+// Only at screen entry points (top-level routes)
+@Composable
+fun LoginRoute(viewModel: LoginViewModel = hiltViewModel()) {
+    LoginScreen(
+        uiState = viewModel.uiState.collectAsState().value,
+        onEmailChanged = viewModel::onEmailChanged,
+        onLoginClick = viewModel::login,
+    )
+}
+```
+
+## Dependency Injection — Hilt
+
+- `@HiltAndroidApp` on Application class
+- `@AndroidEntryPoint` on Activities/Fragments that use injection
+- `@HiltViewModel` for ViewModels
+- Scopes: `@Singleton` for app-wide, `@ActivityScoped` for per-screen
+
+## Navigation — Navigation Compose
+
+```kotlin
+// Define routes as a sealed hierarchy
+sealed class Screen(val route: String) {
+    object Login : Screen("login")
+    data class Profile(val userId: String) : Screen("profile/{userId}")
+}
+
+// NavHost setup
+NavHost(navController, startDestination = Screen.Login.route) {
+    composable(Screen.Login.route) { LoginRoute(navController) }
+    composable("profile/{userId}") { backStackEntry ->
+        ProfileRoute(userId = backStackEntry.arguments?.getString("userId")!!)
+    }
+}
+```
+
+Navigate from ViewModel using a sealed event/effect — never hold NavController in ViewModel.
+
+## Network — Retrofit + OkHttp
+
+```kotlin
+@GET("users/{id}")
+suspend fun getUser(@Path("id") id: String): UserDto
+
+// Add logging interceptor for debug builds only
+if (BuildConfig.DEBUG) {
+    addInterceptor(HttpLoggingInterceptor().apply { level = BODY })
+}
+```