@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/code-reviewer/steering/receiving-feedback.md

@@ -0,0 +1,241 @@
+# Receiving Feedback
+
+> Reference for: Code Reviewer
+> Load when: responding to review comments, handling feedback, review response
+
+---
+
+## Core Mindset
+
+> "Verify before implementing. Ask before assuming. Technical correctness over social comfort."
+
+Code review feedback is a technical discussion, not a social one. Focus on the code, not on feelings.
+
+---
+
+## The Six-Step Process
+
+### Step 1: Read Completely
+
+**Without reacting.** Read the entire comment before forming any response.
+
+```markdown
+❌ BAD: Read first sentence → start typing defense
+✅ GOOD: Read entire comment → understand full context → then respond
+```
+
+### Step 2: Restate Requirements
+
+Rephrase the reviewer's feedback in your own words to confirm understanding.
+
+```markdown
+Reviewer: "This function is doing too much. It handles validation,
+transformation, and persistence all in one place."
+
+Your restatement: "You're suggesting I split this into three separate
+functions: validate(), transform(), and persist()?"
+```
+
+### Step 3: Check Against Codebase
+
+Verify the feedback against actual code conditions before responding.
+
+```typescript
+// Reviewer says: "This will throw if user is null"
+
+// Check the code:
+function getUsername(user: User): string {
+  return user.name;  // No null check - reviewer is correct
+}
+
+// Or discover context:
+function getUsername(user: User): string {
+  return user.name;  // TypeScript enforces User, null not possible
+}
+```
+
+### Step 4: Evaluate Technical Soundness
+
+Consider whether the feedback applies to your specific stack and context.
+
+```markdown
+Reviewer: "You should use useMemo here for performance"
+
+Evaluate:
+- Is this component re-rendering frequently? → Check React DevTools
+- Is the computation expensive? → Profile it
+- Does React 19's compiler auto-optimize this? → Check version
+```
+
+### Step 5: Respond with Substance
+
+Provide technical acknowledgment or reasoned objection.
+
+```markdown
+✅ GOOD: "Fixed. Split into validate(), transform(), persist()
+         at lines 24, 45, 67."
+
+✅ GOOD: "Respectfully disagree. This list has max 5 items
+         (see schema.ts:12), so filter performance is O(5)."
+
+❌ BAD: "You're absolutely right! Great catch!"
+❌ BAD: "I don't think that's necessary."
+```
+
+### Step 6: Implement One at a Time
+
+Address each piece of feedback individually with verification.
+
+```markdown
+Feedback item 1: Add null check
+→ Implement → Test → Commit → Verify → Move to next
+
+Feedback item 2: Extract helper function
+→ Implement → Test → Commit → Verify → Move to next
+
+NOT: Try to address all feedback in one massive commit
+```
+
+---
+
+## Avoiding Agreement Theater
+
+### The Problem
+
+Performative agreement wastes time and provides no information. When you write "Great point!" you're adding noise, not signal.
+
+### Forbidden Phrases
+
+| Phrase | Why It's Wrong |
+|--------|----------------|
+| "You're absolutely right!" | Sycophantic, adds no information |
+| "Great point!" | Empty praise, not a response |
+| "Excellent feedback!" | Flattery, not engagement |
+| "Thanks for catching this!" | Unnecessary, just fix it |
+| "I really appreciate..." | Social fluff, not technical |
+
+### Actions Demonstrate Understanding
+
+```markdown
+❌ "You're absolutely right! Great catch on that null check!
+    Thanks so much for pointing this out!"
+
+✅ "Fixed. Added null check at line 42."
+```
+
+The code change shows you understood. Words are redundant.
+
+### When Acknowledgment IS Appropriate
+
+Brief, technical acknowledgment when learning something new:
+
+```markdown
+✅ "I wasn't aware of that edge case. Added handling at line 42."
+✅ "Good point about thread safety. Added mutex at line 67."
+```
+
+---
+
+## When to Push Back
+
+### Valid Reasons to Disagree
+
+Push back with technical reasoning when feedback:
+
+| Situation | How to Respond |
+|-----------|----------------|
+| Breaks existing functionality | "This change would break Feature X (see test at tests/feature-x.spec.ts:34)" |
+| Lacks full codebase context | "This pattern exists because of Y (see architecture.md#constraints)" |
+| Violates YAGNI | "This flexibility isn't needed yet - only one caller exists" |
+| Is technically incorrect | "This actually works because of Z (link to docs)" |
+| Conflicts with established architecture | "This conflicts with our JWT approach (see auth/README.md)" |
+
+### Good Pushback Format
+
+```markdown
+## Template
+This conflicts with [X]. [Evidence]. Was that the intent, or should we [alternative]?
+
+## Example
+This conflicts with our JWT authentication architecture (see auth/token.js:45).
+Switching to sessions would require restructuring the API middleware.
+Was that the intent, or should we keep JWT?
+```
+
+### Bad Pushback
+
+```markdown
+❌ "I don't think that's right."
+❌ "That won't work."
+❌ "We've always done it this way."
+❌ "That's too much work."
+```
+
+---
+
+## Verification Before Claiming Fixed
+
+### The Checklist
+
+Before writing "Fixed" or "Done":
+
+- [ ] Change is implemented
+- [ ] Tests pass (full suite, not just changed files)
+- [ ] Specific behavior mentioned in feedback is verified
+- [ ] Edge cases are tested
+- [ ] No unintended side effects introduced
+
+### Acceptable Responses
+
+```markdown
+✅ "Fixed. Added null check. Tests pass."
+✅ "Fixed at line 42. Verified with test case X."
+✅ "Implemented. All 47 tests pass."
+```
+
+### Unacceptable Responses
+
+```markdown
+❌ "I think this addresses your concern."
+❌ "Should be fixed now."
+❌ "Done, I believe."
+❌ "Fixed (probably)."
+```
+
+### When You Can't Verify
+
+If you cannot verify a fix:
+
+```markdown
+✅ "Implemented the change, but I'm unable to verify because
+    [specific reason]. Can you confirm on your end?"
+```
+
+---
+
+## Quick Reference
+
+| Situation | Response |
+|-----------|----------|
+| Reviewer is correct | "Fixed. [What you changed]." |
+| You need clarification | "To confirm: you're suggesting [restatement]?" |
+| Reviewer is incorrect | "This works because [evidence]. [Link to proof]." |
+| You disagree on approach | "This conflicts with [X]. Should we [alternative]?" |
+| You learned something | "I wasn't aware of [X]. Fixed at line [N]." |
+| You can't verify | "Implemented. Unable to verify because [reason]." |
+
+---
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Defensive responses | Creates conflict, wastes time | Assume good faith, respond technically |
+| Apologetic responses | Unprofessional, adds noise | Just fix it |
+| Delayed responses | Blocks review cycle | Respond within hours, not days |
+| Vague responses | Leaves reviewer uncertain | Be specific about changes |
+| Ignoring feedback | Disrespectful, creates friction | Address every point |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/Ai Agent Workflow/powers/code-reviewer/steering/report-template.md

@@ -0,0 +1,112 @@
+# Report Template
+
+> Reference for: Code Reviewer
+> Load when: Writing final review report
+
+## Full Review Report Template
+
+```markdown
+# Code Review: [PR Title]
+
+## Summary
+[1-2 sentence overview of the changes and overall assessment]
+
+**Verdict**: [ ] Approve | [x] Request Changes | [ ] Comment
+
+## Critical Issues (Must Fix)
+
+### 1. [File:Line] Security: SQL Injection Risk
+- **Current**: String interpolation in query
+- **Suggested**: Use parameterized query
+- **Impact**: Potential data breach
+
+```typescript
+// Current (vulnerable)
+const query = `SELECT * FROM users WHERE id = ${id}`;
+
+// Suggested (secure)
+const query = 'SELECT * FROM users WHERE id = $1';
+db.query(query, [id]);
+```
+
+## Major Issues (Should Fix)
+
+### 1. [File:Line] Performance: N+1 Query
+- **Current**: Fetching users in loop
+- **Suggested**: Use eager loading with include
+- **Impact**: ~100 extra DB queries per request
+
+### 2. [File:Line] Logic: Missing edge case
+- **Current**: No handling for empty array
+- **Suggested**: Add guard clause
+- **Impact**: Potential runtime error
+
+## Minor Issues (Nice to Have)
+
+### 1. [File:Line] Naming: Unclear variable name
+- **Current**: `d`
+- **Suggested**: `createdDate`
+
+### 2. [File:Line] Style: Inconsistent formatting
+- **Current**: Mixed quotes
+- **Suggested**: Use single quotes consistently
+
+## Positive Feedback
+- Clean separation of concerns in service layer
+- Comprehensive input validation on DTOs
+- Good test coverage for edge cases
+- Excellent error messages
+
+## Questions for Author
+- What's the expected behavior when X happens?
+- Should this support pagination for large datasets?
+- Is the retry logic intentional or accidental?
+
+## Test Coverage Assessment
+- [ ] Happy path tested
+- [x] Error cases tested
+- [ ] Edge cases tested (missing empty array test)
+- [x] Integration tests present
+
+## Checklist
+- [x] No security vulnerabilities
+- [ ] Performance is acceptable (N+1 issue)
+- [x] Code is readable
+- [x] Tests are adequate
+- [x] Documentation is present
+```
+
+## Verdict Guidelines
+
+| Verdict | When to Use |
+|---------|-------------|
+| **Approve** | No blocking issues, minor suggestions only |
+| **Request Changes** | Critical or major issues must be fixed |
+| **Comment** | Questions need answers, no blocking issues |
+
+## Severity Definitions
+
+| Severity | Definition | Examples |
+|----------|------------|----------|
+| **Critical** | Security risk, data loss, crashes | SQL injection, auth bypass |
+| **Major** | Significant performance, maintainability | N+1 queries, god functions |
+| **Minor** | Style, naming, small improvements | Variable names, formatting |
+
+## Time Boxing
+
+| Section | Suggested Time |
+|---------|----------------|
+| Context & understanding | 5 minutes |
+| Critical/security review | 10 minutes |
+| Logic & performance | 15 minutes |
+| Tests review | 10 minutes |
+| Writing report | 10 minutes |
+| **Total** | ~50 minutes |
+
+## Quick Checks Before Submitting
+
+- [ ] All critical issues have clear remediation
+- [ ] Major issues explain the impact
+- [ ] At least one positive comment included
+- [ ] Questions are specific and answerable
+- [ ] Verdict matches the issues found

package/Ai Agent Workflow/powers/code-reviewer/steering/review-checklist.md

@@ -0,0 +1,133 @@
+# Review Checklist
+
+> Reference for: Code Reviewer
+> Load when: Starting a code review
+
+## Comprehensive Review Checklist
+
+| Category           | Key Questions                                                |
+| ------------------ | ------------------------------------------------------------ |
+| **Design**         | Does it fit existing patterns? Right abstraction level?      |
+| **Logic**          | Edge cases handled? Race conditions? Null checks?            |
+| **Security**       | Input validated? Auth checked? Secrets safe?                 |
+| **Performance**    | N+1 queries? Memory leaks? Caching needed?                   |
+| **Tests**          | Adequate coverage? Edge cases tested? Mocks appropriate?     |
+| **Naming**         | Clear, consistent, intention-revealing? File names standard? |
+| **Error Handling** | Errors caught? Meaningful messages? Logged?                  |
+| **Documentation**  | Public APIs documented? Complex logic explained?             |
+| **Code Smells**    | Dead code? Duplication? God objects? Divergent change?       |
+
+## Review Process
+
+### 1. Context (5 min)
+
+- [ ] Read PR description
+- [ ] Understand the problem being solved
+- [ ] Check linked issues/tickets
+- [ ] Note expected changes
+- [ ] Enforce strict rules in strict-rules.md
+
+### 2. Structure (10 min)
+
+- [ ] Review file organization
+- [ ] Check architectural fit
+- [ ] Verify design patterns used
+- [ ] Note any breaking changes
+
+### 3. Code Details (20 min)
+
+- [ ] Review logic correctness
+- [ ] Check edge cases
+- [ ] Verify error handling
+- [ ] Look for security issues
+- [ ] Check performance concerns
+- [ ] Review naming clarity
+- [ ] Flag code smells and unnecessary code
+- [ ] Check for race conditions and unsafe concurrency
+
+### 4. Tests (10 min)
+
+- [ ] Verify test coverage
+- [ ] Check test quality
+- [ ] Look for edge case tests
+- [ ] Ensure mocks are appropriate
+
+### 5. Final Pass (5 min)
+
+- [ ] Note positive patterns
+- [ ] Prioritize feedback
+- [ ] Write summary
+
+## Category Deep Dive
+
+### Design Questions
+
+- Does this change belong in this file/module?
+- Is the abstraction level appropriate?
+- Could this be simpler?
+- Does it follow existing patterns?
+- Is it extensible without modification?
+- Does it follow SOLID where relevant?
+- Is the solution KISS/YAGNI (not over-engineered)?
+
+### Design Principles Quick Check
+
+- **SOLID**: SRP, OCP, LSP, ISP, DIP where applicable
+- **KISS**: simplest working solution
+- **DRY**: no duplicated logic or configs
+- **YAGNI**: avoid speculative features
+- **Separation of Concerns**: clear boundaries between layers
+- **Composition over Inheritance**: favor small composable units
+
+### Logic Questions
+
+- What happens with null/undefined inputs?
+- Are boundary conditions handled?
+- Could there be race conditions?
+- Is the order of operations correct?
+- Are all code paths tested?
+
+### Security Questions
+
+- Is all user input validated?
+- Are SQL queries parameterized?
+- Is output properly encoded?
+- Are secrets handled safely?
+- Is authentication checked?
+- Is authorization enforced?
+
+### Performance Questions
+
+- Are there N+1 query patterns?
+- Is data fetched efficiently?
+- Are expensive operations cached?
+- Could this cause memory leaks?
+- Is pagination implemented?
+
+### Naming & Organization Questions
+
+- Are file names consistent with repo conventions?
+- Do file names describe responsibility clearly?
+- Are functions named with verbs and intent?
+- Are variables descriptive and scoped tightly?
+- Is there one primary concern per file?
+
+### Code Smell Questions
+
+- Is there duplicate logic that can be extracted (DRY)?
+- Is there dead/unused code?
+- Are there long functions/classes with mixed responsibilities (SRP)?
+- Are there “god” objects or utility dumping grounds?
+- Are there hidden side-effects or global state dependencies?
+
+## Quick Reference
+
+| Review Focus             | Time % |
+| ------------------------ | ------ |
+| Context & PR description | 10%    |
+| Architecture & design    | 20%    |
+| Code logic & details     | 40%    |
+| Tests & coverage         | 20%    |
+| Final review & summary   | 10%    |
+
+