triples-agentic 2.4.0

package/src/knowledge/planning/product-principles.md

@@ -0,0 +1,48 @@
+---
+name: product-principles
+description: Core product management principles, user research methods, MVP definition, and definition of done
+---
+
+# Product Management Principles
+
+## Core PM Principles
+
+1. **Fall in love with the problem, not the solution.** The solution will change; the problem should remain stable throughout a product cycle.
+2. **Outcomes over outputs.** Shipping features is not success. User behavior change is success.
+3. **Say no by default.** Every feature added is maintenance burden forever. The default answer to a feature request is "not yet."
+4. **Talk to users.** Assumptions about user behavior are almost always wrong. One user interview beats ten internal debates.
+
+## User Research Methods
+
+### Discovery Research (before PRD)
+- **User interviews** — open-ended, 30–45 min, listen 80% of the time
+- **Job stories** — "When [situation], I want to [motivation], so I can [outcome]"
+- **Competitive analysis** — how do alternatives solve the same problem?
+- **Analytics review** — where do users drop off in the current product?
+
+### Validation Research (during development)
+- **Usability testing** — can users complete core tasks without help?
+- **A/B testing** — which variant achieves better outcomes at scale?
+- **Beta feedback** — structured feedback from early adopters
+
+## MVP Definition
+
+An MVP is the smallest thing that proves (or disproves) your core hypothesis.
+
+An MVP is NOT:
+- A scaled-down version of the full product
+- Something with "all the basics"
+- A prototype with no real users
+
+An MVP IS:
+- One user journey, done end-to-end
+- Enough to get real feedback from real users
+- Deployable and measurable
+
+## Definition of Done (Product Perspective)
+
+A feature is done when:
+- It meets all acceptance criteria in the PRD
+- It has been tested by a real user (or QA standing in)
+- Success metrics are instrumented and tracking
+- Documentation is updated if applicable

package/src/knowledge/planning/product-prioritization.md

@@ -0,0 +1,45 @@
+---
+name: product-prioritization
+description: Prioritization frameworks (RICE, MoSCoW), stakeholder communication, and feature request handling
+---
+
+# Product Prioritization & Stakeholder Communication
+
+## Prioritization Frameworks
+
+### RICE Score
+- **Reach** — how many users affected per time period?
+- **Impact** — how much does it move the metric? (1=minimal, 3=massive)
+- **Confidence** — how sure are we? (expressed as %)
+- **Effort** — person-weeks to build
+- Score = (Reach × Impact × Confidence) / Effort
+
+### MoSCoW
+- **Must have** — without this, the product fails
+- **Should have** — important but workarounds exist
+- **Could have** — nice to have, cut if time is tight
+- **Won't have** — explicitly out of scope for this release
+
+### Opportunity Scoring
+Rate each opportunity on two axes:
+- How important is this to users? (1–10)
+- How satisfied are users with current solutions? (1–10)
+
+High importance + low satisfaction = highest priority opportunity.
+
+## Stakeholder Communication
+
+- **Weekly status**: what shipped, what's next, what's blocked — 5 bullets max
+- **Scope changes**: always quantify impact on timeline before escalating
+- **Feature requests from stakeholders**: "What outcome are you trying to drive?" before writing a line of spec
+- **Engineering pushback**: legitimate technical concerns modify scope; never override without understanding the constraint
+- **Conflict resolution**: trace every requirement back to a user need; if it can't be traced, cut it
+
+## Handling Feature Requests
+
+1. "What problem does this solve for the user?"
+2. "What happens if we don't build this?"
+3. "How many users face this problem, and how often?"
+4. "What's the simplest version that proves value?"
+
+Never say "yes, we'll build it." Say "yes, we'll consider it in the next planning cycle against other priorities."

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

@@ -0,0 +1,38 @@
+---
+name: rfc-quality-gates
+description: RFC quality gate checklist, anti-patterns, and evaluation criteria for implementation readiness
+---
+
+# RFC Quality Gates & Anti-Patterns
+
+## Quality Gates
+
+ALL of the following must pass before an RFC is marked implementation-ready:
+
+- [ ] **Architecture decision** — the chosen approach is stated clearly with a rationale
+- [ ] **Alternatives documented** — at least 2 alternatives considered and rejected with reasoning
+- [ ] **Data model** — entities and relationships defined (even if approximate)
+- [ ] **API contracts** — public interfaces defined with request/response shapes
+- [ ] **Risk assessment** — at least one risk identified with a mitigation
+- [ ] **Rollback plan** — how to undo this change if it goes wrong
+- [ ] **No scope creep** — RFC stays within the bounds of the approved PRD
+- [ ] **Open questions closed** — no unresolved technical blockers before handoff
+
+## Evaluation Output
+
+Run all gates and output exactly one of:
+
+- `✅ READY — RFC meets all quality gates.`
+- `❌ GAPS FOUND: [numbered list of failing gates with specific technical questions to resolve]`
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| "We'll figure out the DB schema later" | Blocks task estimation | Design the schema now, mark as draft |
+| RFC written after code is done | Not a design doc, a post-mortem | Write RFC before implementation |
+| No alternatives section | Appears like the first idea was the only idea | Always document what was rejected |
+| "Industry standard approach" without citation | Vague justification | Name the standard and link to it |
+| Mixing security concerns into every section | Hard to review | Dedicated security section |
+| Rollout plan missing | No way to safely deploy | Always include feature flag + rollback |
+| Vague risk ("could be slow") | Not actionable | Quantify: "p95 > 500ms under 1000 RPS" |

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

@@ -0,0 +1,81 @@
+---
+name: rfc-writing
+description: How to write a Request for Comments — structure, trade-off analysis, alternatives, and rollout planning
+---
+
+# RFC Writing — Structure & Standards
+
+## What an RFC Is
+
+A Request for Comments is a technical design document that proposes HOW to build something. It is written after the PRD (what/why) is approved. The RFC:
+- Documents the chosen technical approach and its trade-offs
+- Surfaces risks before code is written
+- Creates a record of technical decisions and why they were made
+- Collects feedback from the team before implementation begins
+
+## RFC Structure
+
+```
+# RFC: [Feature / System Name]
+**Status:** Draft | Under Review | Approved | Superseded
+**Author:** [Name]
+**Date:** YYYY-MM-DD
+**Related PRD:** workspace/PRD.md
+
+## Summary
+One paragraph: what is being built, using what approach, and the key trade-off accepted.
+
+## Motivation
+Why are we building this now? Reference the PRD problem statement.
+
+## Technical Proposal
+### Architecture Overview
+High-level diagram or description of how components interact.
+
+### Data Model
+Key entities, relationships, and storage approach.
+
+### API Contracts
+Endpoint definitions, request/response shapes, authentication.
+
+### Key Algorithms / Business Logic
+Non-trivial logic that needs design attention.
+
+### Infrastructure & Deployment
+Where does this run? How does it scale? What observability is needed?
+
+## Alternatives Considered
+For each alternative: what is it, why was it rejected?
+
+## Trade-offs & Risks
+What are we giving up? What could go wrong? Include mitigation for each risk.
+
+## Migration Plan
+If this changes existing behavior: how do we migrate data and users safely?
+
+## Rollout Plan
+Feature flag strategy, phased rollout, rollback procedure.
+
+## Open Questions
+Technical questions that need resolution before or during implementation.
+```
+
+## Writing Principles
+
+1. **One decision per RFC.** An RFC that tries to design three systems is too big. Split it.
+2. **State the trade-off explicitly.** "We chose X. This means we accept Y."
+3. **Diagrams beat prose.** ASCII diagrams, sequence diagrams, and ER diagrams communicate faster.
+4. **Separate what from how.** Architecture section = what components exist. Implementation section = how each works.
+5. **Date every decision.** Technology landscapes change. A decision that made sense in 2022 may not in 2025.
+
+## Architecture Decision Records (ADR)
+
+For decisions that affect the whole system, write a formal ADR:
+
+```
+# ADR-XXX: [Decision Title]
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Context:** Why does this decision need to be made?
+**Decision:** What was decided?
+**Consequences:** What does this mean going forward?
+```

package/src/knowledge/planning/task-decomposition.md

@@ -0,0 +1,61 @@
+---
+name: task-decomposition
+description: Task hierarchy (epic/story/task), decomposition rules, story mapping, and sprint planning conventions
+---
+
+# Task Decomposition
+
+## Hierarchy
+
+```
+Initiative (months)
+  └── Epic (weeks)
+        └── User Story (days)
+              └── Task (hours)
+```
+
+- **Initiative**: a strategic goal ("launch mobile app")
+- **Epic**: a large body of work that delivers meaningful value ("user authentication")
+- **User Story**: a single user-facing unit of value ("user can log in with email/password")
+- **Task**: a technical work item ("implement JWT middleware")
+
+## Decomposition Rules
+
+1. **One task = one concern.** If a task has an "and" in the title, split it.
+2. **Tasks must be independently completable.** A task blocked by another should list the dependency explicitly.
+3. **No task should be longer than 2 days (16h).** If it is, decompose it further.
+4. **Every task must have testable acceptance criteria.** "Done" is not a criterion.
+5. **Estimate at the task level, not story level.** Roll up estimates bottom-up.
+
+## Story Mapping
+
+Story mapping organises user stories by user journey (x-axis) and priority/release (y-axis):
+
+```
+User Journey →  Login  →  Browse  →  Purchase  →  Receipt
+                -------    -------    ----------    -------
+MVP (Row 1)     Email       List       Cart          Email
+                login       view       checkout      receipt
+
+v1.1 (Row 2)    Social      Search     Saved cards   PDF
+                login       filter     (1-click)     download
+```
+
+Walk the journey before breaking into tasks. This prevents building features in the wrong order.
+
+## Sprint Planning Conventions
+
+- Sprint capacity = (team size × days per sprint × hours per day) × 0.7 (sustainable pace)
+- Use yesterday's weather for velocity: if the team completes 30 points per sprint, plan 30 points
+- Leave 20% capacity for bug fixes, tech debt, and unplanned work
+- Never plan more than 80% of individual capacity
+
+## Infrastructure Tasks
+
+Technical tasks required by the RFC that don't map to user stories must also be included:
+- Database migrations and schema setup
+- CI/CD pipeline configuration
+- Third-party service integration setup
+- Environment and secrets configuration
+
+These should be estimated and sequenced like any other task.

package/src/knowledge/planning/task-readiness.md

@@ -0,0 +1,64 @@
+---
+name: task-readiness
+description: Task format template, definition of done, and readiness checklist for tasks before development starts
+---
+
+# Task Readiness & Format
+
+## Task Format
+
+```markdown
+## Task: [Short imperative title]
+
+**Story Points:** [1 / 2 / 3 / 5 / 8 / 13]
+**Estimated Hours:** [X–Y hours]
+**Assignee:** [Agent name or role]
+**Dependencies:** [Task IDs this depends on]
+**Platform:** [Web / Android / iOS / Flutter / Backend / All]
+
+### Description
+One paragraph of what needs to be done and why.
+
+### Acceptance Criteria
+- [ ] Criterion 1 (testable, binary pass/fail)
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+### Technical Notes
+Any non-obvious implementation notes, constraints, or gotchas.
+
+### Definition of Done
+- [ ] Code written and reviewed
+- [ ] Unit tests passing
+- [ ] Integrated and verified in dev environment
+- [ ] QA signed off (for user-facing changes)
+```
+
+## Readiness Checklist (Is a Task Ready to Start?)
+
+- [ ] Acceptance criteria are written and agreed upon
+- [ ] Dependencies are identified and unblocked (or sequenced)
+- [ ] Story points are estimated by the person who will do the work
+- [ ] Design assets/mockups are available (for UI tasks)
+- [ ] API contracts are defined (for integration tasks)
+- [ ] The task fits within one sprint (≤ 2 days / 16 hours)
+
+## Dependency Mapping
+
+Express dependencies explicitly between tasks:
+
+```
+TASK-I01 (DB setup)
+    └── TASK-001 (API endpoint)
+            └── TASK-002 (Frontend integration)
+                    └── TASK-003 (UI polish)
+```
+
+Never start a task with unresolved upstream dependencies. If the dependency can't be resolved, flag it to the orchestrator (SeoYeon) immediately.
+
+## Evaluation Output
+
+Run all gates and output exactly one of:
+
+- `✅ READY — All tasks meet the readiness checklist.`
+- `❌ GAPS FOUND: [numbered list of specific unclear or missing items]`

package/src/knowledge/quality/qa-execution.md

@@ -0,0 +1,55 @@
+---
+name: qa-execution
+description: QA execution process — pre-test checklist, smoke testing, exploratory testing, and platform-specific considerations
+---
+
+# QA Execution
+
+## QA Role
+
+The QA Engineer's job is to find real problems before users do — not to rubber-stamp development output. A QA engineer who never finds bugs is not doing their job; a QA engineer who blocks release without evidence is equally unhelpful.
+
+## Execution Process
+
+### 1. Pre-Testing Checklist
+- [ ] Build/deployment confirmed stable
+- [ ] Test environment matches target environment (data, config)
+- [ ] Test data and fixtures are in place
+- [ ] Test cases reviewed and understood
+- [ ] Feature scope confirmed with developer
+
+### 2. Smoke Testing First
+Run P0 test cases only. If smoke tests fail, **stop and report immediately** — do not continue with full test suite on an unstable build.
+
+### 3. Systematic Execution
+Execute in priority order: P0 → P1 → P2 → P3.
+Document actual result for every test case: Pass / Fail / Blocked / Skipped (with reason).
+
+### 4. Exploratory Testing
+After structured cases:
+- Try unexpected inputs and sequences
+- Check edge cases not covered in test cases
+- Test integrations between new and existing features
+- Verify consistency with the rest of the product
+
+## Platform-Specific Considerations
+
+### Web
+- Browsers: Chrome (latest), Firefox (latest), Safari (latest), Edge (latest)
+- Viewports: 375px (mobile), 768px (tablet), 1440px (desktop)
+- Check: keyboard navigation, screen reader (VoiceOver/NVDA), print styles
+
+### Android
+- OS versions: latest + one 2-year-old version
+- Devices: low-end (budget RAM) + flagship
+- Check: back button, rotation, dark mode, large font size, split-screen
+
+### iOS
+- OS versions: latest + one version back
+- Devices: iPhone SE (small) + iPhone Pro Max (large)
+- Check: safe area insets, Dynamic Type, VoiceOver, landscape mode
+
+### Flutter (Cross-Platform)
+- Run on both Android and iOS
+- Verify platform-adaptive widgets render correctly on each
+- Check system font integration and text scale

package/src/knowledge/quality/qa-reporting.md

@@ -0,0 +1,71 @@
+---
+name: qa-reporting
+description: Bug report format, go/no-go release criteria, automation strategy, and QA metrics
+---
+
+# QA Reporting & Release Criteria
+
+## Bug Report Format
+
+```markdown
+## BUG-[ID]: [Short descriptive title]
+
+**Severity:** Critical | High | Medium | Low
+**Priority:** P0 | P1 | P2 | P3
+**Status:** Open | In Progress | Fixed | Verified | Won't Fix
+**Platform:** Web Chrome 120 / Android 14 / iOS 17.2 / Flutter
+**Build/Version:** [build number or commit SHA]
+
+### Steps to Reproduce
+1. [Exact step]
+2. [Exact step]
+
+### Expected Result
+[What should have happened]
+
+### Actual Result
+[What actually happened — error messages verbatim]
+
+### Evidence
+[Screenshot, screen recording, log output]
+
+### Notes
+[Frequency: always/intermittent; related issues]
+```
+
+## Go/No-Go Criteria
+
+### Ship (Go)
+- All P0 test cases: PASS
+- All P1 test cases: PASS or accepted risk documented
+- No Critical or High severity bugs open without explicit sign-off
+- Regression tests: PASS
+
+### Do Not Ship (No-Go)
+- Any P0 test case FAIL without a valid workaround
+- Any Critical severity bug open
+- High severity bug count above team's defined threshold
+- Core user flow (login, purchase, core CRUD) broken
+
+Document every No-Go with: failing test cases, severity, estimated fix time, and what would change the recommendation.
+
+## Automation Strategy
+
+**Automate when**:
+- Test case is P0 or P1
+- Test runs more than once per sprint
+- Test is time-consuming but fully deterministic
+
+**Keep manual when**:
+- Exploratory or visual testing
+- Test requires subjective judgment
+- Feature is likely to change soon (automate after stabilization)
+
+## QA Metrics
+
+| Metric | Target | Notes |
+|---|---|---|
+| Defect detection rate | > 90% before production | % found by QA vs users |
+| Test case pass rate | > 95% before release | Track per sprint for trends |
+| Bug re-open rate | < 10% | Indicates fix quality issues |
+| Mean time to verify fix | < 1 day | Blockers should not sit |

package/src/knowledge/quality/test-case-quality.md

@@ -0,0 +1,61 @@
+---
+name: test-case-quality
+description: Test case quality gates, priority levels, suite organisation, and traceability matrix
+---
+
+# Test Case Quality Gates & Organisation
+
+## Priority Levels
+
+| Priority | Definition | Examples |
+|---|---|---|
+| **P0 Critical** | App crashes, data loss, security breach, core flow broken | Login broken, payment fails |
+| **P1 High** | Major feature doesn't work; workaround is difficult | Cart can't be updated |
+| **P2 Medium** | Feature works but degrades experience | Wrong error message |
+| **P3 Low** | Minor cosmetic issue | Typo, incorrect tooltip |
+
+## Quality Gates
+
+ALL of the following must pass before a test case set is marked implementation-ready:
+
+- [ ] Every PRD acceptance criterion has at least one test case
+- [ ] Happy path covered for all user stories
+- [ ] At least 2 negative/error path cases per major feature
+- [ ] Edge cases documented for all input fields
+- [ ] P0 test cases identified for smoke test suite
+- [ ] All test cases have specific, binary expected results (no "works correctly")
+- [ ] Preconditions are unambiguous for all test cases
+- [ ] Test data requirements documented
+- [ ] Platform coverage specified for all test cases
+
+## Evaluation Output
+
+- `✅ READY — Test case suite meets all quality gates.`
+- `❌ GAPS FOUND: [numbered list of specific missing scenarios or vague criteria]`
+
+## Test Suite Structure
+
+```
+Test Suite: [Feature Name]
+├── Smoke Tests (P0 only — run on every deploy, < 5 min)
+├── Regression Tests (P0 + P1 — run before release)
+├── Full Test Suite (all priorities — run nightly)
+└── Exploratory Testing Notes (manual, unscripted sessions)
+```
+
+## Traceability Matrix
+
+| Test Case | User Story | Acceptance Criterion |
+|---|---|---|
+| TC-001 | US-01 | AC-01.1 |
+| TC-002 | US-01 | AC-01.2 (error state) |
+| TC-003 | US-02 | AC-02.1 |
+
+## Automation Candidates
+
+Flag test cases that should be automated (P0 and P1 that run frequently):
+
+| TC ID | Framework |
+|---|---|
+| TC-001 | Playwright / XCUITest / Espresso |
+| TC-002 | Playwright |

package/src/knowledge/quality/test-case-writing.md

@@ -0,0 +1,76 @@
+---
+name: test-case-writing
+description: Test case format, types (positive/negative/edge/boundary), and writing principles for reproducible test cases
+---
+
+# Test Case Writing
+
+## What Is a Test Case
+
+A test case is a documented procedure that verifies whether a specific feature or behavior works as expected. It is the contract between QA and development.
+
+A well-written test case is:
+- **Specific**: one scenario per test case
+- **Reproducible**: anyone can run it and get the same result
+- **Independent**: does not depend on the result of another test case
+- **Traceable**: linked back to a requirement or user story
+
+## Test Case Format
+
+```markdown
+## TC-[ID]: [Short descriptive title]
+
+**Related Requirement:** [PRD section / User Story ID]
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Type:** Functional | UI | Performance | Security | Accessibility
+**Platform:** Web | Android | iOS | Flutter | All
+
+### Preconditions
+State the system must be in before the test begins.
+- User is logged in with a standard account
+
+### Test Steps
+1. Navigate to [screen/URL]
+2. Perform [action] on [element]
+3. Enter [specific data — not "valid input", use real values like test@example.com]
+
+### Expected Result
+What the system SHOULD do after the steps above.
+- Screen displays "Order confirmed" message
+- Email sent within 30 seconds
+- Order appears in history with status "Pending"
+
+### Status
+[ ] Pass | [ ] Fail | [ ] Blocked | [ ] Skipped
+```
+
+## Test Types
+
+### Positive (Happy Path)
+Tests the intended workflow with valid inputs.
+- User logs in with valid credentials → lands on dashboard
+
+### Negative (Error Paths)
+Tests what happens with invalid inputs or unexpected actions.
+- User logs in with wrong password → error message shown
+
+### Edge Cases
+Tests boundaries and unusual but valid scenarios.
+- User enters maximum allowed characters (255) in a field
+- User has 0 items in cart and attempts checkout
+
+### Boundary Testing
+Tests exact boundary values:
+- Min: field minimum = 1 char → enter 1 (pass), enter 0 (fail)
+- Max: field max = 255 chars → enter 255 (pass), enter 256 (fail)
+
+### Regression Tests
+Tests that previously working functionality has not broken after a change.
+
+## Writing Principles
+
+1. **Write for someone who has never seen the feature.** No assumed context.
+2. **One expected result per test case.** If you have "and then", split the test.
+3. **Be specific about data.** "Enter a valid email" is worse than "Enter `test@example.com`".
+4. **Distinguish UI state from system state.** "Button becomes disabled" (UI) vs "Record is saved to DB" (system).
+5. **Link every test case to a requirement.** Orphaned test cases are usually outdated.

package/src/knowledge/quality/testing-strategy.md

@@ -0,0 +1,70 @@
+---
+name: testing-strategy
+description: Testing pyramid, shift-left testing, test naming conventions, and common testing anti-patterns
+---
+
+# Testing Strategy
+
+## Testing Pyramid
+
+```
+        /\
+       /  \    E2E Tests (few, slow, expensive)
+      /----\   — Critical user flows only
+     /      \
+    /--------\  Integration Tests (some, medium speed)
+   /          \ — Service boundaries, API contracts
+  /------------\ Unit Tests (many, fast, cheap)
+ /              \— Pure functions, business logic, utilities
+```
+
+**Rule of thumb**: 70% unit, 20% integration, 10% E2E.
+
+## Test Naming Convention
+
+```
+[unit_of_work]_[state_under_test]_[expected_behavior]
+```
+
+Examples:
+- `login_withValidCredentials_returnsAuthToken()`
+- `cart_whenItemAdded_totalUpdatesCorrectly()`
+- `formatCurrency_withNegativeValue_showsMinusSign()`
+
+## Shift-Left Testing
+
+Testing starts at requirements, not after development:
+1. Review acceptance criteria during PRD phase
+2. Write test cases before (or alongside) implementation
+3. Run unit tests in pre-commit hooks
+4. Run integration tests in CI on every PR
+5. E2E tests run nightly or before every release
+
+## Testing Anti-Patterns
+
+| Anti-Pattern | Problem |
+|---|---|
+| Testing implementation, not behavior | Tests break on refactoring, not on bugs |
+| Mocking everything | Tests pass but production still fails |
+| Shared mutable state between tests | Flaky tests, order-dependent failures |
+| Sleep/wait in tests | Slow and flaky — use await/callbacks instead |
+| Huge test setup | Indicates code is not testable — refactor |
+| No assertion in test | Test always passes — caught by linting |
+
+## Test Doubles
+
+| Type | Description | Use when |
+|---|---|---|
+| **Stub** | Returns fixed value | Predictable output needed |
+| **Mock** | Verifies interactions | Testing that a method was called |
+| **Fake** | Working implementation | Need realistic behavior (in-memory DB) |
+| **Spy** | Wraps real object | Verify calls while keeping real behavior |
+
+Prefer **fakes** over **mocks** — they reveal interface misuse; mocks can pass when the contract is wrong.
+
+## Coverage
+
+- Target: 80%+ line coverage for business logic
+- Track **branch** coverage, not just line coverage
+- 100% coverage does NOT mean no bugs
+- Never write tests just to hit a number — test behavior, not lines