@vpxa/aikit 0.1.1

package/scaffold/general/skills/multi-agents-development/code-quality-review-prompt.md

@@ -0,0 +1,91 @@
+# Code Quality Review Prompt Template
+
+Use this template when dispatching **Code-Reviewer-Alpha** and **Code-Reviewer-Beta** for dual code quality review. Both reviewers get the same prompt — different models catch different issues.
+
+This review runs AFTER spec compliance passes.
+
+---
+
+## Prompt Template
+
+```markdown
+You are performing a code quality review. The code has already passed spec compliance — it does what was asked. Your job is to evaluate HOW it does it.
+
+## Task Context
+[Brief description of what was implemented and why]
+
+## Files Changed
+[List of files with a one-line description of changes in each]
+
+## Code Diff
+[Paste the actual code changes — full diff or new file contents]
+
+---
+
+## Review Dimensions
+
+### 1. Readability & Maintainability
+- Are names clear and intention-revealing?
+- Is the code self-documenting or does it need comments?
+- Is complexity managed (small functions, single responsibility)?
+- Would a new team member understand this in 5 minutes?
+
+### 2. Pattern Adherence
+- Does the code follow the project's established patterns?
+- Are there inconsistencies with surrounding code?
+- Are there framework idioms being violated?
+
+### 3. Error Handling & Edge Cases
+- Are errors handled at appropriate boundaries?
+- Are edge cases considered (null, empty, overflow, concurrent access)?
+- Are error messages helpful for debugging?
+
+### 4. Performance
+- Any obvious N+1 queries or unnecessary iterations?
+- Any blocking operations that should be async?
+- Any missing caching opportunities or unnecessary allocations?
+
+### 5. Security
+- Input validation present for external data?
+- No secrets in code?
+- No injection vulnerabilities (SQL, XSS, command)?
+- Proper authorization checks?
+
+### 6. Spec Alignment (Cross-Check)
+- Does the implementation match what was requested?
+- Any over-engineering beyond requirements?
+- Any subtle deviations from the intended behavior?
+
+### 7. Testability
+- Is the code testable in isolation?
+- Are dependencies injectable?
+- Are there missing test cases?
+
+---
+
+## Output Format
+
+### Verdict: [APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES]
+
+**APPROVE** — Code is production-ready.
+**APPROVE_WITH_SUGGESTIONS** — Good to merge, but consider these improvements.
+**REQUEST_CHANGES** — Must fix before proceeding. List blocking issues.
+
+### Findings:
+| # | Dimension | Severity | Description | Location | Suggestion |
+|---|-----------|----------|-------------|----------|------------|
+| 1 | [Dimension] | [Blocker/Major/Minor/Nit] | [Issue] | [file:line] | [Fix] |
+
+### Summary:
+[2-3 sentence overall assessment]
+```
+
+---
+
+## Usage Notes
+
+- Both Alpha and Beta reviewers get this same template — multi-model cross-validation
+- Combine findings from both reviewers before deciding on action
+- **Blocker** findings = REQUEST_CHANGES (must fix)
+- **Major** findings = usually REQUEST_CHANGES unless truly optional
+- **Minor/Nit** = APPROVE_WITH_SUGGESTIONS (fix in follow-up or ignore)

package/scaffold/general/skills/multi-agents-development/implementer-prompt.md

@@ -0,0 +1,93 @@
+# Implementer Dispatch Prompt Template
+
+Use this template when dispatching **Implementer**, **Frontend**, or **Refactor** agents.
+
+Fill in the bracketed sections with task-specific content. The Orchestrator provides ALL context — the subagent should NOT need to search/explore.
+
+---
+
+## Prompt Template
+
+```markdown
+You are implementing a focused task. All context you need is provided below. Do NOT search for additional files or read the full plan — work only within the scope defined here.
+
+## 1. Scope
+**Files to create/modify:**
+- [exact/path/to/file1.ts] — [create | modify]
+- [exact/path/to/file2.ts] — [create | modify]
+
+**Boundary — do NOT touch:**
+- [files/that/are/off/limits.ts]
+- [other/agents/territory/]
+
+## 2. Goal
+[Clear description of what the code should do]
+
+**Acceptance criteria:**
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+- [ ] [Specific, testable criterion 3]
+
+## 3. Architectural Context
+[Relevant code snippets, patterns, conventions from compact/digest — paste actual code, don't reference files]
+
+Example existing pattern:
+\`\`\`typescript
+// From services/auth.service.ts — follow this pattern
+export class AuthService {
+  constructor(private readonly repo: AuthRepository) {}
+  async validate(token: string): Promise<User> { ... }
+}
+\`\`\`
+
+## 4. Constraints
+- Follow [specific pattern/convention]
+- Use [specific library/approach]
+- Do NOT [specific anti-pattern to avoid]
+- [Any other boundaries]
+
+## 5. FORGE Context
+**Tier:** [Floor | Standard | Critical]
+**Evidence requirements:** [What evidence to collect — test results, type coverage, etc.]
+
+## 6. Self-Review Checklist
+Before declaring your status, verify ALL:
+- [ ] All acceptance criteria from §2 are met
+- [ ] No files outside §1 scope were modified
+- [ ] Code follows conventions from §3 and constraints from §4
+- [ ] Tests pass (run them if possible)
+- [ ] No TODO/FIXME/HACK left without justification
+- [ ] No hardcoded values that should be configurable
+
+---
+
+**STATUS PROTOCOL — End your response with EXACTLY ONE:**
+
+### DONE
+All tasks complete. Self-review checklist passed. Ready for review.
+
+### DONE_WITH_CONCERNS
+All tasks complete, but I have concerns:
+- [Concern 1: description + suggested resolution]
+- [Concern 2: description + suggested resolution]
+
+### NEEDS_CONTEXT
+Cannot proceed without the following:
+- [Specific question or missing information]
+
+### BLOCKED
+Hit a wall and cannot proceed:
+- [Description of blocker]
+- [What I tried]
+- [Suggestion for resolution]
+```
+
+---
+
+## Usage Notes
+
+- **Always paste actual code snippets** in §3 — use `compact()` or `digest()` to extract relevant context before crafting the prompt
+- **Keep scope tight** — 1-3 files maximum per dispatch
+- **Include failing test output** if dispatching a bug fix
+- **For Frontend agent**: add design requirements, responsive breakpoints, component hierarchy
+- **For Refactor agent**: include before/after expectations, what specifically to clean up

package/scaffold/general/skills/multi-agents-development/parallel-dispatch-example.md

@@ -0,0 +1,167 @@
+# Parallel Dispatch Worked Example
+
+This example shows how the Orchestrator decomposes a feature into parallel tasks, crafts context for each subagent, and manages the batch through review.
+
+---
+
+## Scenario: Add User Notification Preferences
+
+**User request:** "Add a notification preferences page where users can toggle email, push, and in-app notifications per category (marketing, security, product updates)."
+
+---
+
+## Step 1: Scope Map & Decomposition
+
+Orchestrator runs `scope_map({ task: "notification preferences" })` and identifies:
+
+| Area | Files | Agent |
+|------|-------|-------|
+| Backend API | `services/notification-prefs.service.ts`, `routes/notification-prefs.route.ts` | Implementer |
+| Database | `migrations/add-notification-prefs.ts`, `models/notification-prefs.model.ts` | Implementer |
+| Frontend Page | `pages/settings/notifications.tsx`, `components/NotificationToggle.tsx` | Frontend |
+| Tests | `__tests__/notification-prefs.test.ts` | Implementer |
+
+## Step 2: Independence Check (5-Question Checklist)
+
+| # | Question | Backend API + DB | Frontend Page |
+|---|----------|-----------------|---------------|
+| 1 | Same files? | `services/`, `routes/`, `migrations/`, `models/` | `pages/`, `components/` |
+| 2 | Shared state? | No — backend defines API contract | No — consumes API contract |
+| 3 | Execution order? | No — can define API while UI is built | No — can mock API response |
+| 4 | Shared new types? | Exports `NotificationPrefs` type | Imports same type |
+| 5 | Parallel-safe? | ✅ Yes — different directories | ✅ Yes — different directories |
+
+**Decision: PARALLEL** — But first define the shared type contract.
+
+## Step 3: Shared Context Prep
+
+Before dispatching, Orchestrator creates the shared contract:
+
+```typescript
+// Type contract — paste into BOTH agent prompts
+interface NotificationPrefs {
+  userId: string;
+  categories: {
+    marketing: { email: boolean; push: boolean; inApp: boolean };
+    security: { email: boolean; push: boolean; inApp: boolean };
+    product: { email: boolean; push: boolean; inApp: boolean };
+  };
+  updatedAt: Date;
+}
+
+// API contract
+// GET  /api/notifications/preferences → NotificationPrefs
+// PUT  /api/notifications/preferences → NotificationPrefs (body: Partial<NotificationPrefs['categories']>)
+```
+
+## Step 4: Parallel Dispatch
+
+### Dispatch A → Implementer (Backend + DB + Tests)
+
+```markdown
+You are implementing a focused task. All context below.
+
+## 1. Scope
+- services/notification-prefs.service.ts — create
+- routes/notification-prefs.route.ts — create
+- migrations/add-notification-prefs.ts — create
+- models/notification-prefs.model.ts — create
+- __tests__/notification-prefs.test.ts — create
+
+## 2. Goal
+Create backend API for notification preferences CRUD.
+- GET endpoint returns current prefs (default all-true for new users)
+- PUT endpoint updates partial categories
+- Migration creates notification_preferences table
+
+## 3. Architectural Context
+[Paste existing service pattern from compact()]
+[Paste existing route pattern from compact()]
+[Paste existing migration pattern from compact()]
+[Paste the shared type contract above]
+
+## 4. Constraints
+- Follow existing repository pattern (see §3)
+- Use Zod for request validation
+- Include unit tests for service layer
+
+## 5. FORGE Context
+Tier: Standard. Evidence: test pass, type coverage.
+
+## 6. Self-Review Checklist
+[standard checklist]
+
+STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+```
+
+### Dispatch B → Frontend (UI Page + Components)
+
+```markdown
+You are implementing a focused task. All context below.
+
+## 1. Scope
+- pages/settings/notifications.tsx — create
+- components/NotificationToggle.tsx — create
+
+## 2. Goal
+Create notification preferences settings page.
+- Grid layout: rows = categories, columns = channels
+- Toggle switches for each cell
+- Auto-save on toggle (optimistic update with rollback)
+- Loading skeleton on initial fetch
+
+## 3. Architectural Context
+[Paste existing settings page pattern from compact()]
+[Paste existing toggle component from compact()]
+[Paste the shared type contract + API contract above]
+
+## 4. Constraints
+- Use existing Toggle component from design system
+- Follow settings page layout pattern
+- Mobile responsive (stack columns on small screens)
+- Mock API response for now: GET returns all-true defaults
+
+## 5. FORGE Context
+Tier: Floor. Evidence: renders without error.
+
+## 6. Self-Review Checklist
+[standard checklist]
+
+STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+```
+
+## Step 5: Review Pipeline
+
+Both agents return DONE. Orchestrator runs review:
+
+1. **Spec Review** (Code-Reviewer-Alpha as spec reviewer):
+   - Backend: PASS — all acceptance criteria met
+   - Frontend: PASS_WITH_NOTES — missing keyboard accessibility on toggles
+
+2. **Code Quality Review** (Alpha + Beta in parallel):
+   - Alpha: APPROVE_WITH_SUGGESTIONS — extract validation schema to shared file
+   - Beta: APPROVE — clean implementation
+
+3. **Architecture Review** (not triggered — no boundary changes)
+
+4. **FORGE Gate**: `evidence_map({ action: "gate" })` → YIELD (all evidence collected)
+
+## Step 6: Commit
+
+```
+feat: add notification preferences page
+
+- Backend: CRUD API for notification preferences per category
+- Frontend: Settings page with toggle grid, auto-save
+- Migration: notification_preferences table
+```
+
+---
+
+## Key Takeaways
+
+1. **Define shared contracts FIRST** — paste into all agent prompts
+2. **Independence check takes 30 seconds** — prevents hours of merge conflicts
+3. **Each agent gets ONLY its files** — focused context = better output
+4. **Review is sequential** — spec first, then quality, then architecture (conditional)
+5. **FORGE gates at the end** — not between every step

package/scaffold/general/skills/multi-agents-development/spec-review-prompt.md

@@ -0,0 +1,81 @@
+# Spec Compliance Review Prompt Template
+
+Use this template when dispatching **Code-Reviewer-Alpha** for adversarial spec compliance review. This review runs BEFORE code quality review.
+
+**Mindset: "Don't trust the report."** The implementer says it's done — verify independently.
+
+---
+
+## Prompt Template
+
+```markdown
+You are performing an adversarial spec compliance review. Your job is to verify that the implementation matches what was requested — nothing more, nothing less.
+
+**Do NOT trust the implementer's self-assessment.** Verify independently.
+
+## Task Specification
+[Paste the original task that was dispatched to the implementer — including all acceptance criteria]
+
+## Implementation Output
+[Paste the implementer's response — code changes, self-review, status]
+
+## Files Changed
+[List of files modified with brief description of changes]
+
+---
+
+## Review Dimensions
+
+### 1. Acceptance Criteria Match
+For EACH acceptance criterion in the task spec:
+- [ ] **Met** / **Not Met** / **Partially Met**
+- Evidence: [specific code or test that proves it]
+
+### 2. Over-Build Detection
+- Are there features, functions, or abstractions NOT requested in the spec?
+- Are there unnecessary generalizations?
+- Were files modified outside the stated scope?
+→ Flag each over-build with: what was added, why it shouldn't be there
+
+### 3. Under-Build Detection
+- Are any acceptance criteria unaddressed?
+- Are there edge cases implied by the spec but not handled?
+- Are there missing tests for stated requirements?
+→ Flag each under-build with: what's missing, what should exist
+
+### 4. Scope Compliance
+- List every file modified — does it match the scope in the original task?
+- Were any out-of-scope files touched? (this is a red flag)
+
+### 5. Contract Adherence
+- Do new exports/interfaces match what other components expect?
+- Are function signatures compatible with existing callers?
+- Will this break anything downstream?
+
+---
+
+## Output Format
+
+### Verdict: [PASS | PASS_WITH_NOTES | FAIL]
+
+**PASS** — Implementation matches spec completely.
+**PASS_WITH_NOTES** — Matches spec but has minor concerns that don't block.
+**FAIL** — Implementation does not match spec. List specific gaps.
+
+### Findings:
+| # | Type | Severity | Description | Location |
+|---|------|----------|-------------|----------|
+| 1 | [Over/Under/Scope/Contract] | [Critical/Major/Minor] | [Description] | [file:line] |
+
+### Recommendation:
+[What needs to change before this passes spec review]
+```
+
+---
+
+## Usage Notes
+
+- Run this BEFORE code quality review — no point reviewing quality if spec is wrong
+- Paste the ORIGINAL task spec, not a summary — the reviewer needs exact acceptance criteria
+- If verdict is FAIL, bounce back to implementer with specific gaps before proceeding
+- PASS_WITH_NOTES can proceed to code quality review, but notes should be tracked