triples-agentic 2.4.0

package/src/knowledge/mobile/ios/ios-platform.md

@@ -0,0 +1,66 @@
+---
+name: ios-platform
+description: Apple Human Interface Guidelines compliance, local storage patterns, iOS testing, and App Store requirements
+---
+
+# iOS — Platform & Distribution
+
+## Apple Human Interface Guidelines (HIG) Compliance
+
+- **Navigation**: use `NavigationStack` (iOS 16+); respect back button behavior
+- **Tab bars**: 3–5 tabs maximum; icons must have text labels
+- **Modals**: use for tasks that interrupt workflow; always provide a dismiss mechanism
+- **Typography**: use Dynamic Type — never hardcode font sizes
+- **Color**: use semantic colors (`Color(.systemBackground)`, `.label`) for automatic dark mode
+- **Safe areas**: always respect safe area insets; never overlap system chrome
+- **Touch targets**: minimum 44×44pt for all interactive elements
+
+## Modifier Order Convention
+
+```swift
+Text("Hello")
+    .font(.headline)        // 1. Typography
+    .foregroundColor(.blue) // 2. Color
+    .padding()              // 3. Internal spacing
+    .background(.gray)      // 4. Background
+    .cornerRadius(8)        // 5. Shape
+    .padding(.horizontal)   // 6. External spacing
+```
+
+## Local Storage
+
+| Use case | Solution |
+|---|---|
+| Complex relational data | Core Data or SwiftData (iOS 17+) |
+| Simple settings | UserDefaults |
+| Sensitive data (tokens, passwords) | Keychain |
+| Files, documents | FileManager |
+
+Never store credentials in UserDefaults.
+
+## Testing
+
+- **XCTest / Swift Testing** (Xcode 16+): unit tests for ViewModels, use cases, utilities
+- **XCUITest**: E2E UI testing for critical user flows
+- Mock with protocols — inject dependencies via initializer, not global singletons
+
+```swift
+// Protocol-based mocking
+protocol UserRepository {
+    func fetchUser(id: String) async throws -> User
+}
+
+class MockUserRepository: UserRepository {
+    var mockUser: User = .mock
+    func fetchUser(id: String) async throws -> User { mockUser }
+}
+```
+
+## App Store Requirements
+
+- **Privacy manifest** (`PrivacyInfo.xcprivacy`) required for all new apps
+- **Privacy nutrition labels** must accurately reflect data collection
+- **In-app purchases** must use StoreKit (no external payment links for digital goods)
+- **Age-appropriate design** requirements for apps targeting children
+- **Screenshots** required for every supported device size
+- **App Review Guidelines section 4.0**: apps must follow iOS design patterns

package/src/knowledge/mobile/ios/swift-concurrency.md

@@ -0,0 +1,99 @@
+---
+name: swift-concurrency
+description: Swift async/await, structured concurrency, actors, protocols, generics, and memory management (ARC)
+---
+
+# Swift — Concurrency & Advanced Patterns
+
+## async/await
+
+```swift
+// Async function
+func fetchUser(id: String) async throws -> User {
+    let (data, _) = try await URLSession.shared.data(from: url)
+    return try JSONDecoder().decode(User.self, from: data)
+}
+
+// Calling async code
+Task {
+    do {
+        let user = try await fetchUser(id: "123")
+        await MainActor.run { self.user = user }
+    } catch { print("Error: \(error)") }
+}
+
+// Parallel execution
+async let userFetch = fetchUser(id: userId)
+async let ordersFetch = fetchOrders(userId: userId)
+let (user, orders) = try await (userFetch, ordersFetch)
+```
+
+## @MainActor
+
+UI updates must happen on the main actor:
+
+```swift
+@MainActor
+func updateUI(with user: User) {
+    self.nameLabel.text = user.name  // safe on main thread
+}
+
+// ViewModel marked as @MainActor
+@MainActor
+class ProfileViewModel: ObservableObject {
+    @Published var user: User?
+    func load() async { user = try? await userRepo.fetch() }
+}
+```
+
+## Protocols & Generics
+
+```swift
+// Protocol with associated type
+protocol Repository {
+    associatedtype Model
+    func fetch(id: String) async throws -> Model
+    func save(_ model: Model) async throws
+}
+
+// Generic function
+func first<T>(in array: [T], where condition: (T) -> Bool) -> T? {
+    array.first(where: condition)
+}
+```
+
+## Memory Management (ARC)
+
+- ARC manages memory automatically — no manual `malloc`/`free`
+- **Retain cycles**: break with `weak` or `unowned` in closures
+
+```swift
+class MyClass {
+    var closure: (() -> Void)?
+
+    func setup() {
+        closure = { [weak self] in  // prevents retain cycle
+            self?.doSomething()
+        }
+    }
+}
+```
+
+- `weak`: nullable, use when referenced object may be deallocated
+- `unowned`: non-nullable, use only when certain the object outlives the reference
+
+## Mixins (Protocol Extensions)
+
+```swift
+protocol Serializable {
+    func toJson() -> [String: Any]
+}
+
+extension Serializable {
+    func toJsonString() -> String {
+        (try? JSONSerialization.data(withJSONObject: toJson())).flatMap {
+            String(data: $0, encoding: .utf8)
+        } ?? "{}"
+    }
+}
+```

package/src/knowledge/mobile/ios/swift-core.md

@@ -0,0 +1,79 @@
+---
+name: swift-core
+description: Swift optionals, value vs reference types, error handling, and the Swift API Design Guidelines
+---
+
+# Swift — Core Language
+
+## Optionals
+
+```swift
+var name: String? = nil
+
+// Optional binding (preferred)
+if let name = name { print("Name: \(name)") }
+
+// Guard (preferred for early exits)
+guard let name = name else { return }
+
+// Nil coalescing
+let displayName = name ?? "Anonymous"
+
+// Optional chaining
+let count = name?.count
+```
+
+## Value Types vs Reference Types
+
+```swift
+// Struct (value type) — prefer for data models
+struct User {
+    var id: String
+    var name: String
+}
+
+// Class (reference type) — use for shared mutable state, ViewModels
+class UserViewModel: ObservableObject {
+    @Published var user: User?
+}
+
+// Enum with associated values
+enum PaymentMethod {
+    case creditCard(last4: String)
+    case paypal(email: String)
+    case applePay
+}
+```
+
+## Error Handling
+
+```swift
+enum AuthError: Error, LocalizedError {
+    case invalidCredentials
+    case networkUnavailable
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidCredentials: return "Invalid email or password"
+        case .networkUnavailable: return "No internet connection"
+        }
+    }
+}
+
+// Throw and catch
+do {
+    let token = try await login(email: email, password: password)
+} catch AuthError.invalidCredentials {
+    showError("Check your email and password")
+} catch {
+    showError(error.localizedDescription)
+}
+```
+
+## Swift API Design Guidelines
+
+- **Clarity at the call site**: `x.insert(y, at: z)` reads better than `x.insert(y, z)`
+- **Name methods for their side effects**: mutating → verb (`append`); non-mutating → noun (`sorted`)
+- **Boolean names read as assertions**: `isEmpty`, `isValid`, `canSubmit`
+- **Parameter labels clarify arguments**: `move(from: a, to: b)` not `move(a, b)`
+- **Avoid abbreviations**: `numberOfLines` not `numLines`

package/src/knowledge/planning/architecture-database.md

@@ -0,0 +1,47 @@
+---
+name: architecture-database
+description: Database selection guide, scalability checklist, and observability stack for production systems
+---
+
+# Architecture — Database & Scalability
+
+## Database Selection Guide
+
+| Need | Recommended | Why |
+|---|---|---|
+| Relational data, ACID transactions | PostgreSQL | Industry standard, excellent tooling |
+| Simple key-value cache | Redis | Fast, well-supported |
+| Document storage, flexible schema | MongoDB | Schema flexibility, good horizontal scaling |
+| Full-text search | Elasticsearch / Meilisearch | Built for search |
+| Time-series data | TimescaleDB / InfluxDB | Efficient for append-heavy, time-indexed data |
+| Graph relationships | Neo4j | Native graph traversal |
+
+**Default to PostgreSQL** unless there is a specific, documented reason not to.
+
+## Scalability Checklist
+
+Before designing for scale, verify you actually need it. Then:
+- [ ] Stateless application servers (scale horizontally, not vertically)
+- [ ] Database read replicas for read-heavy workloads
+- [ ] CDN for static assets
+- [ ] Caching layer (Redis) for expensive computed results
+- [ ] Async queues for long-running tasks
+- [ ] Rate limiting at API gateway
+
+## Observability Stack
+
+Every production system needs:
+- **Logging**: structured JSON logs, correlation IDs across service calls
+- **Metrics**: request rate, error rate, latency (p50/p95/p99)
+- **Tracing**: distributed trace IDs through all service hops
+- **Alerting**: page on error rate spikes and latency degradation — not on CPU%
+
+## Background Jobs
+
+Use queues (BullMQ, Sidekiq, Celery) for:
+- Email/notification sending
+- File processing
+- External API calls with retries
+- Report generation
+
+Every job must: log start/end, handle errors gracefully, be idempotent (safe to retry).

package/src/knowledge/planning/architecture-patterns.md

@@ -0,0 +1,64 @@
+---
+name: architecture-patterns
+description: Software architecture patterns (layered, event-driven, microservices, CQRS) with trade-off analysis
+---
+
+# Architecture Patterns
+
+## Foundational Principles
+
+1. **Simple before clever.** A boring, well-understood pattern that works beats an elegant abstraction that surprises the team.
+2. **Design for failure.** Every external call can fail. Every database can go down. Design the happy path last.
+3. **Defer decisions.** Don't choose a message queue before you know you need one. Premature architecture is technical debt with extra steps.
+4. **Observability first.** If you can't measure it, you can't debug it in production.
+
+## Common Architectural Patterns
+
+### Layered (N-Tier)
+```
+Presentation → Application / Business Logic → Data Access → Storage
+```
+- Best for: CRUD-heavy applications, well-understood domains
+- Trade-off: Layer coupling, hard to scale individual layers
+
+### Event-Driven
+```
+Producer → Event Bus → Consumer(s)
+```
+- Best for: Decoupled services, audit trails, async workflows
+- Trade-off: Eventual consistency, harder to debug
+
+### Microservices
+```
+API Gateway → Service A, Service B, Service C (each with own DB)
+```
+- Best for: Teams that need to deploy independently, mixed tech stacks
+- Trade-off: Network overhead, distributed tracing complexity, operational burden
+
+### Monolith (Recommended for v1)
+```
+Single deployable unit: routes + business logic + DB access
+```
+- Best for: Early-stage products, small teams, fast iteration
+- Trade-off: Harder to scale specific hotspots as traffic grows
+
+### CQRS (Command Query Responsibility Segregation)
+```
+Write path: Command → Aggregate → Event → Write Store
+Read path: Read Store (denormalized views)
+```
+- Best for: High-read systems with complex reporting needs
+- Trade-off: Two models to maintain, eventual consistency
+
+## API Design Patterns
+
+### REST
+- Resources are nouns, HTTP verbs define actions
+- `GET /users/123` — read; `POST /users` — create; `PATCH /users/123` — update
+- Status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error
+- Pagination: cursor-based preferred over offset for large datasets
+
+### GraphQL
+- Single endpoint, client specifies exact data shape
+- Use when: multiple clients (web, mobile) with different data needs
+- Avoid when: simple CRUD, team unfamiliar with the overhead

package/src/knowledge/planning/architecture-security.md

@@ -0,0 +1,61 @@
+---
+name: architecture-security
+description: Security fundamentals for system design — authentication, authorization, secrets management, and input validation
+---
+
+# Architecture — Security Fundamentals
+
+## Authentication
+
+- **JWT**: stateless APIs; access token (15–60 min) + refresh token (7–30 days, httpOnly cookie)
+- **Session cookies**: server-rendered apps with stateful sessions
+- Never store JWTs in localStorage (XSS risk)
+
+```
+1. Client sends credentials → POST /auth/login
+2. Server validates → returns { access_token, refresh_token }
+3. Client sends: Authorization: Bearer <access_token>
+4. Server validates JWT signature + expiry on every request
+5. Refresh via POST /auth/refresh with refresh_token
+```
+
+## Authorization
+
+### RBAC (Role-Based Access Control)
+```
+User → has Role(s) → Role has Permissions → Permission gates resources/actions
+```
+Check authorization in the service layer, not the route handler.
+
+### ABAC (Attribute-Based Access Control)
+Use only for complex policy requirements where RBAC becomes unmanageable.
+
+## Secrets Management
+
+- **Never** commit secrets to version control
+- Use environment variables + secrets manager (HashiCorp Vault, AWS SSM, GCP Secret Manager)
+- Rotate secrets on a schedule; immediately on suspected leak
+- Different secrets per environment (dev/staging/prod)
+
+## Input Validation
+
+- Validate and sanitize **at the API boundary** — never trust client input
+- Use parameterized queries or ORMs — never string concatenation in SQL
+- Validate content type, size, and shape before processing files/uploads
+- Sanitize HTML output; never use `innerHTML` with user content
+
+## Transport Security
+
+- **HTTPS everywhere**: TLS 1.2 minimum; TLS 1.3 preferred
+- Redirect all HTTP to HTTPS; enforce with HSTS header
+- `Strict-Transport-Security: max-age=31536000; includeSubDomains`
+
+## Common Vulnerabilities to Prevent
+
+| Vulnerability | Prevention |
+|---|---|
+| SQL Injection | Parameterized queries / ORM |
+| XSS | Escape output; CSP headers; never innerHTML with user data |
+| CSRF | SameSite cookies + CSRF tokens for state-changing operations |
+| Sensitive data exposure | Encrypt at rest and in transit; never log PII or tokens |
+| Broken access control | Enforce authorization server-side on every request |

package/src/knowledge/planning/estimation.md

@@ -0,0 +1,82 @@
+---
+name: estimation
+description: Fibonacci story points, time estimates, planning poker, velocity tracking, and release planning
+---
+
+# Estimation Knowledge — Story Points & Time Estimates
+
+## Story Points (Fibonacci Scale)
+
+Story points measure **relative complexity**, not hours. The Fibonacci sequence forces meaningful gaps between sizes.
+
+| Points | Complexity | Typical scope |
+|--------|-----------|---------------|
+| 1 | Trivial | Rename a field, fix a typo, update a config value |
+| 2 | Simple | Add a new field to an existing form, write a simple API endpoint |
+| 3 | Moderate | New CRUD feature with basic validation, simple mobile screen |
+| 5 | Complex | Feature with multiple states, external API integration, new DB table + API |
+| 8 | Large | New user-facing flow across multiple screens, complex business logic |
+| 13 | Very large | Epic-level scope — should be decomposed further before sprint |
+| 21+ | Too big | Always decompose. This is a placeholder, not an estimate. |
+
+## Time Estimates
+
+Pair story points with time estimates for project planning:
+
+| Story Points | Time Estimate | Notes |
+|---|---|---|
+| 1 | 1–2 hours | Single developer, minimal review needed |
+| 2 | 2–4 hours | Half-day work |
+| 3 | 4–8 hours | Full day |
+| 5 | 1–2 days | May span sprint boundaries |
+| 8 | 2–4 days | Needs careful scoping before start |
+| 13 | 1–2 weeks | Decompose before committing |
+
+These are medians. Adjust for:
+- **Unfamiliar technology**: +50–100%
+- **Cross-team dependencies**: +20%
+- **Legacy codebase**: +30–50%
+- **Clear requirements + prior art**: -20%
+
+## Estimation Anti-Patterns
+
+| Anti-Pattern | Problem |
+|---|---|
+| Estimating in ideal hours | Ignores interruptions, meetings, reviews. Use calendar time. |
+| PM estimating for engineers | The person doing the work estimates. Always. |
+| Anchoring ("I think it's 3, right?") | Biases the group. Use blind voting (planning poker). |
+| Skipping estimation for "quick tasks" | Quick tasks are where scope surprises come from. |
+| Re-estimating mid-sprint when it's harder | Estimate once; capture actuals for calibration. |
+
+## Planning Poker Protocol
+
+1. Facilitator reads the story and acceptance criteria aloud
+2. Each estimator privately selects a card (1, 2, 3, 5, 8, 13)
+3. All cards revealed simultaneously
+4. Outliers (highest and lowest) explain their reasoning
+5. Re-vote until consensus or facilitator decides
+
+## Velocity Tracking
+
+Track actuals vs. estimates every sprint:
+
+```
+Sprint N: Committed 32 pts → Completed 28 pts → Velocity: 28
+Sprint N+1: Committed 28 pts → Completed 30 pts → Velocity: 29
+Sprint N+2: Use rolling 3-sprint average for planning capacity
+```
+
+Never punish teams for lower velocity — punishment creates inflated estimates.
+
+## Release Planning with Estimates
+
+```
+Remaining story points: 150
+Team velocity (3-sprint avg): 30 pts/sprint
+Sprints remaining: 150 / 30 = 5 sprints
+Sprint length: 2 weeks
+Estimated completion: 10 weeks from today
+Confidence: Medium (add 20% buffer = 12 weeks for a commitment)
+```
+
+Always present estimates as ranges, not point estimates. "8–12 weeks" is more honest than "10 weeks."

package/src/knowledge/planning/orchestration.md

@@ -0,0 +1,70 @@
+---
+name: orchestration
+description: Agent workflow sequencing, delegation protocol, escalation rules, and artifact tracking
+---
+
+# Orchestration Knowledge — Workflow Coordination
+
+## Role of the Engineering Manager in Agent Orchestration
+
+The orchestrator's job is to route work, not do it. Delegate early, track progress, escalate blockers.
+
+## Standard Workflow Sequence
+
+```
+User Input → PRD → RFC → Task Breakdown → (Dev ∥ Test Cases) → QA → Delivery
+```
+
+Human review gates are mandatory at: PRD, RFC, Task Breakdown, Test Cases.
+Development and Test Case creation run in parallel once Task Breakdown is approved.
+
+## Delegation Protocol
+
+When handing off to another agent, include:
+- The artifact generated so far (path to file)
+- The user's original intent (verbatim if possible)
+- Any decisions already locked in
+- Open questions the next agent should address
+
+## Escalation Rules
+
+Escalate to the user (not another agent) when:
+- Two agents disagree on a foundational decision (scope, tech choice, timeline)
+- A quality gate has been blocked for more than 2 review iterations
+- A requirement contradicts a previously approved decision
+
+Never silently skip a gate or merge conflicting requirements without human sign-off.
+
+## Artifact Tracking
+
+All artifacts land in `workspace/` at the project root:
+```
+workspace/
+├── PRD.md
+├── RFC.md
+├── TASK_BREAKDOWN.md
+├── TEST_CASES.md
+└── DELIVERY_SUMMARY.md
+```
+
+Reference artifacts by path, not by memory, to avoid drift between agent contexts.
+
+## Run State
+
+Maintain a mental model of which stage the current run is in:
+
+| Stage | Agent | Status |
+|---|---|---|
+| PRD | JiWoo | pending / in-progress / review / approved |
+| RFC | YooYeon | pending / in-progress / review / approved |
+| Task Breakdown | NaKyoung | pending / in-progress / review / approved |
+| Development | YuBin, Kaede, YeonJi, SoHyun, Kotone | pending / in-progress / done |
+| Test Cases | Lynn | pending / in-progress / review / approved |
+| QA | ShiOn | pending / in-progress / done |
+
+## Communication Style for Engineering Managers
+
+- Be direct. State what's happening, what's blocked, and what you need.
+- Do not hedge. If a gate fails, say it fails. If a decision is needed, say who decides.
+- Summarize status in terms of delivery risk, not internal process steps.
+- Keep handoff messages short — the receiving agent reads the artifact, not your narration.

package/src/knowledge/planning/prd-quality-gates.md

@@ -0,0 +1,38 @@
+---
+name: prd-quality-gates
+description: PRD quality gate checklist, anti-patterns to avoid, and pass/fail evaluation criteria
+---
+
+# PRD Quality Gates & Anti-Patterns
+
+## Quality Gates
+
+ALL of the following must pass before a PRD is marked implementation-ready:
+
+- [ ] **Problem statement** — clear, specific, one paragraph, explains user pain
+- [ ] **Primary persona** — at least one user persona defined with goals and context
+- [ ] **Feature scope** — both in-scope AND out-of-scope explicitly stated
+- [ ] **User stories** — at least 3 stories covering core journeys
+- [ ] **Acceptance criteria** — every major feature has measurable pass/fail criteria (no vague "works well")
+- [ ] **Success metrics** — at least one quantitative metric defined
+- [ ] **No implementation leak** — PRD does not prescribe tech stack, architecture, or database choices
+- [ ] **Open questions addressed** — no blockers left unanswered before handoff
+
+## Evaluation Output
+
+Run all gates and output exactly one of:
+
+- `✅ READY — PRD meets all quality gates.`
+- `❌ GAPS FOUND: [numbered list of failing gates with specific questions to resolve]`
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It's Wrong | Fix |
+|---|---|---|
+| "The system should be fast" | Not measurable | "Page load under 2s on 3G" |
+| "Use React for the frontend" | PRD prescribes implementation | Move to RFC |
+| "TBD" on acceptance criteria | Engineers can't test against TBD | Resolve before handoff |
+| Features listed without personas | No context for priority decisions | Add who benefits and why |
+| 40-page PRD for an MVP | Overspecification kills agility | Cut to what's needed for v1 |
+| "And" in a user story | Too many concerns in one story | Split into separate stories |
+| Acceptance criteria with "should" | "Should" is not binary | Use "must" or rewrite as Given/When/Then |

package/src/knowledge/planning/prd-writing.md

@@ -0,0 +1,59 @@
+---
+name: prd-writing
+description: How to write a Product Requirements Document — structure, user stories, acceptance criteria, and writing principles
+---
+
+# PRD Writing — Structure & Standards
+
+## What a PRD Is
+
+A Product Requirements Document defines WHAT to build and WHY — never HOW. It is the contract between product and engineering. Engineers should be able to implement from it without asking the PM for clarification.
+
+## PRD Structure
+
+```
+# Product Requirements Document: [Feature Name]
+
+## Problem Statement
+One paragraph. What user problem are we solving? Why does it matter?
+
+## User Personas
+Who are the primary users? What are their goals, frustrations, and context?
+
+## Feature Scope
+### In Scope
+Bulleted list of what this product/feature includes.
+
+### Out of Scope
+Explicit list of what is NOT included in this release. This is as important as in-scope.
+
+## User Stories
+As a [persona], I want [goal] so that [benefit].
+Include 3–10 stories that cover the core user journeys.
+
+## Acceptance Criteria
+For each major feature, list measurable pass/fail criteria.
+Use: "Given [context], when [action], then [outcome]."
+
+## Success Metrics
+How will we know this feature succeeded? Include quantitative targets.
+
+## Non-Functional Requirements
+Performance, security, accessibility, internationalization constraints.
+
+## Dependencies & Risks
+What other teams, systems, or data sources does this depend on?
+What could go wrong?
+
+## Open Questions
+Questions that need resolution before or during development.
+```
+
+## Writing Principles
+
+1. **One truth per sentence.** Each bullet should be independently testable.
+2. **Persona-first.** Always trace a requirement back to a user need.
+3. **Explicit scope.** If you don't say it's out of scope, engineers will assume it's in scope.
+4. **No ambiguity in criteria.** "User can log in" is not a criterion. "User can log in with email+password within 3 seconds" is.
+5. **Short is better.** A lean, clear PRD ships faster than a complete one that nobody reads.
+6. **No implementation leak.** The PRD must not prescribe tech stack, architecture, or database choices — those belong in the RFC.