@vpxa/aikit 0.1.4 → 0.1.5

package/scaffold/general/agents/Orchestrator.agent.md

@@ -128,6 +128,18 @@ Batch 2 (after batch 1):
 - Charts, tables, dependency graphs → always `present`
 - Short confirmations and questions → normal chat
 
+## Subagent Output Relay
+
+When subagents complete, their visual outputs (from `present`) are NOT visible to the user.
+**You MUST relay key findings:**
+
+1. After every subagent completes, extract key data from the returned text
+2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })`
+3. If the subagent returns structured findings → summarize and present to user
+4. **Never assume the user saw subagent output** — always relay or re-present
+
+**Rule: Every subagent batch completion MUST be followed by a user-visible summary or presentation.**
+
 ## Critical Rules
 
 1. 🚫 **ZERO implementation** — never `editFiles`/`createFile` on source code. Always delegate.
@@ -139,6 +151,33 @@ Batch 2 (after batch 1):
 7. **Never proceed without user approval** at 🛑 stops
 8. **Max 2 retries** then escalate to user
 
+## Delegation Enforcement
+
+**You are a conductor, not a performer.** Before every action, run this self-check:
+
+> Am I about to write, edit, or create source code myself? → **STOP. Delegate instead.**
+
+### Forbidden Tools (Orchestrator must NEVER use these on source code)
+- `replace_string_in_file` / `editFiles`
+- `create_file` / `createFile`
+- `multi_replace_string_in_file`
+- `run_in_terminal` for code generation (sed, echo >>, etc.)
+
+### Allowed Tools (Orchestrator uses these directly)
+- `search`, `compact`, `digest`, `file_summary`, `scope_map`, `symbol`, `trace`
+- `present`, `remember`, `stash`, `checkpoint`, `restore`
+- `check`, `test_run`, `blast_radius`, `reindex`, `produce_knowledge`
+- `forge_classify`, `forge_ground`, `evidence_map`
+- `runSubagent` — your PRIMARY tool for getting work done
+- `read_file` — ONLY to gather context for subagent prompts
+
+### Pre-Action Gate
+Before every tool call, verify:
+1. Is this a **read/analysis** tool? → ✅ Proceed
+2. Is this a **presentation/memory** tool? → ✅ Proceed
+3. Is this a **file modification** tool? → 🚫 Delegate to subagent
+4. Is this a **terminal command** that changes files? → 🚫 Delegate to subagent
+
 ## Skills (load on demand)
 
 | Skill | When to load |
@@ -147,3 +186,33 @@ Batch 2 (after batch 1):
 | `brainstorming` | Before creative/design work (Phase 0) |
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |
+
+## Flow-Aware Routing
+
+At session start, check for an active flow:
+1. Call `flow_status` to check if a flow is active
+2. If active and status is 'active':
+   - Note the current step name and skill path
+   - Load the current step's skill file
+   - Follow its instructions for this step
+   - When step is complete, call `flow_step({ action: 'next' })`
+3. If no active flow:
+   - Check `flow_list` for available flows
+   - Suggest starting a flow based on the task type
+   - Use `flow_start({ flow: '<name>' })` to begin
+
+### Flow MCP Tools
+| Tool | Purpose |
+|------|---------|
+| `flow_list` | List installed flows and active flow |
+| `flow_info` | Get detailed flow info including steps |
+| `flow_start` | Start a named flow |
+| `flow_step` | Advance: next, skip, or redo current step |
+| `flow_status` | Check current execution state |
+| `flow_reset` | Clear flow state to start over |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Planner.agent.md

@@ -38,6 +38,18 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 5. **Dependency Graph** — For each phase, list dependencies. Group into parallel batches
 6. **Present** — Show plan with open questions, complexity estimate, parallel batch layout
 
+## Subagent Output Relay
+
+When subagents complete, their visual outputs (from `present`) are NOT visible to the user.
+**You MUST relay key findings:**
+
+1. After every subagent completes, extract key data from the returned text
+2. If the subagent mentions charts, tables, or visual data → re-present using `present({ format: "html" })`
+3. If the subagent returns structured findings → summarize and present to user
+4. **Never assume the user saw subagent output** — always relay or re-present
+
+**Rule: Every subagent batch completion MUST be followed by a user-visible summary or presentation.**
+
 ## Output Format
 
 ```markdown
@@ -77,3 +89,9 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 | `c4-architecture` | When the plan involves architectural changes — generate C4 diagrams |
 | `adr-skill` | When the plan involves non-trivial technical decisions — create executable ADRs |
 | `session-handoff` | When context window is filling up, planning session ending, or major milestone completed |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Refactor.agent.md

@@ -34,3 +34,9 @@ You are the **Refactor**, code refactoring specialist that improves structure, r
 | Skill | When to load |
 |-------|--------------|
 | `lesson-learned` | After completing a refactor — extract principles from the before/after diff |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Researcher-Alpha.agent.md

@@ -18,3 +18,9 @@ You are **Researcher-Alpha**, the primary deep research agent. During multi-mode
 | `lesson-learned` | When analyzing past changes to extract engineering principles |
 | `c4-architecture` | When researching system architecture — produce C4 diagrams |
 | `adr-skill` | When the research involves a technical decision — draft an ADR |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -18,3 +18,9 @@ You are **Researcher-Beta**, a variant of the Researcher agent. You exist to pro
 | `lesson-learned` | When analyzing past changes to extract engineering principles |
 | `c4-architecture` | When researching system architecture — produce C4 diagrams |
 | `adr-skill` | When the research involves a technical decision — draft an ADR |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -18,3 +18,9 @@ You are **Researcher-Delta**, a variant of the Researcher agent. You exist to pr
 | `lesson-learned` | When analyzing past changes to extract engineering principles |
 | `c4-architecture` | When researching system architecture — produce C4 diagrams |
 | `adr-skill` | When the research involves a technical decision — draft an ADR |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -18,3 +18,9 @@ You are **Researcher-Gamma**, a variant of the Researcher agent. You exist to pr
 | `lesson-learned` | When analyzing past changes to extract engineering principles |
 | `c4-architecture` | When researching system architecture — produce C4 diagrams |
 | `adr-skill` | When the research involves a technical decision — draft an ADR |
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/Security.agent.md

@@ -53,3 +53,9 @@ You are the **Security**, security specialist that analyzes code for vulnerabili
 ### Findings
 1. **[SEVERITY]** Title — Description, file:line, remediation
 ```
+
+## Flows
+
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -3,6 +3,25 @@
 > This file contains shared protocols for all code-modifying agents (Implementer, Frontend, Refactor, Debugger). Each agent's definition file contains only its unique identity, constraints, and workflow. **Do not duplicate this content in agent files.**
 
 
+## AI Kit MCP Tool Naming Convention
+
+All tool references in these instructions use **short names** (e.g. `status`, `compact`, `search`).
+At runtime, these are MCP tools exposed by the AI Kit server. Depending on your IDE/client, the actual tool name will be prefixed:
+
+| Client | Tool naming pattern | Example |
+|--------|-------------------|---------|
+| VS Code Copilot | `mcp_<serverName>_<tool>` | `mcp_aikit_status` |
+| Claude Code | `mcp__<serverName>__<tool>` | `mcp__aikit__status` |
+| Other MCP clients | `<serverName>_<tool>` or bare `<tool>` | `aikit_status` or `status` |
+
+The server name is typically `aikit` or `kb` — check your MCP configuration.
+
+**When these instructions say** `status({})` **→ call the MCP tool whose name ends with** `_status` **and pass** `{}` **as arguments.**
+
+If tools are deferred/lazy-loaded, load them first (e.g. in VS Code Copilot: `tool_search_tool_regex({ pattern: "aikit" })`).
+
+---
+
 ## Invocation Mode Detection
 
 You may be invoked in two modes:
@@ -10,6 +29,9 @@ You may be invoked in two modes:
 2. **Sub-agent** (via Orchestrator) — you may have limited MCP tool access.
    The Orchestrator provides context under "## Prior AI Kit Context" in your prompt.
    If present, skip AI Kit Recall and use the provided context instead.
+  **Visual Output:** When running as a sub-agent, do NOT use the `present` tool (output won't reach the user).
+  Instead, include structured data (tables, findings, metrics) as formatted text in your final response.
+  The Orchestrator will re-present relevant content to the user.
 
 **Detection:** If your prompt contains "## Prior AI Kit Context", you are in sub-agent mode.
 

package/scaffold/general/prompts/ask.prompt.md

@@ -7,8 +7,8 @@ tools:
   - aikit/web_fetch
   - aikit/compact
   - aikit/file_summary
-  - aikit/present
   - aikit/remember
+  - aikit/present
 ---
 
 ## Quick Research

package/scaffold/general/prompts/debug.prompt.md

@@ -11,6 +11,7 @@ tools:
   - aikit/parse_output
   - aikit/compact
   - aikit/remember
+  - aikit/present
 ---
 
 ## Debug Workflow

package/scaffold/general/prompts/implement.prompt.md

@@ -10,6 +10,7 @@ tools:
   - aikit/blast_radius
   - aikit/remember
   - aikit/audit
+  - aikit/present
 ---
 
 ## Implementation Pipeline

package/scaffold/general/prompts/plan.prompt.md

@@ -9,8 +9,8 @@ tools:
   - aikit/file_summary
   - aikit/analyze_structure
   - aikit/analyze_dependencies
-  - aikit/present
   - aikit/remember
+  - aikit/present
 ---
 
 ## Planning Workflow

package/scaffold/general/prompts/review.prompt.md

@@ -7,8 +7,8 @@ tools:
   - aikit/check
   - aikit/test_run
   - aikit/analyze_dependencies
-  - aikit/present
   - aikit/remember
+  - aikit/present
 ---
 
 ## Review Pipeline

package/scaffold/general/skills/frontend-design/SKILL.md

@@ -0,0 +1,225 @@
+# Frontend Design
+
+> Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.
+
+## When to Use
+
+**MANDATORY** for the Frontend agent on every task. Also use when:
+- Building any UI component, page, or layout
+- Styling, theming, or visual design work
+- Reviewing UI for quality, accessibility, or design consistency
+- User says "make it look good", "design", "UI", "styling", "responsive", "dark mode", "animation"
+
+## Context Gathering Protocol
+
+Before any design work, gather answers to these questions (infer from codebase if user doesn't specify):
+
+1. **Design System** — Does one exist? Tokens, variables, component library?
+2. **Brand Guidelines** — Colors, fonts, logo usage, tone?
+3. **Accessibility Requirements** — WCAG level (AA default), assistive tech?
+4. **Responsive Breakpoints** — Mobile-first? Specific breakpoints?
+5. **Motion Preferences** — Animation budget, reduced-motion support?
+6. **Content Model** — CMS, static, dynamic, i18n?
+7. **Dark Mode** — Required? System preference detection?
+8. **Target Platforms** — Desktop, mobile web, tablet, native?
+
+## Design Thinking Process
+
+Follow this cycle: **Understand → Explore → Evaluate → Refine**
+
+1. **Understand** — What is the user trying to accomplish? What are the constraints?
+2. **Explore** — Generate at minimum 2-3 distinct design directions. Name each direction. Describe the aesthetic and rationale.
+3. **Evaluate** — Compare against requirements, accessibility, performance, and the AI Slop Test.
+4. **Refine** — Iterate on the chosen direction. Polish details.
+
+## Typography
+
+### Hierarchy
+- Use a **clear scale**: display → h1 → h2 → h3 → body → caption → overline
+- Maximum **3 font sizes** per viewport visible at once
+- Use `font-weight` to create hierarchy within same size
+- Line height: 1.5 for body text, 1.2-1.3 for headings
+- **Fluid typography**: use `clamp()` for responsive sizing — e.g., `clamp(1rem, 2.5vw, 1.5rem)`
+
+### Rules
+- Never use more than 2 typeface families
+- Ensure minimum **16px** body text on mobile
+- Use `rem` for font sizes, `em` for component-relative spacing
+- Monospace only for code: use a dedicated code font family
+- Set `max-width: 65ch` on text blocks for readability
+- Use `text-wrap: balance` on headings, `text-wrap: pretty` on body
+- Provide room for **text expansion** (50%+) for i18n
+
+## Color
+
+### 60-30-10 Rule
+- **60%** — Background/surface (neutral)
+- **30%** — Secondary/container (brand subtle)
+- **10%** — Accent/CTA (brand strong)
+
+### Systematic Color
+- Define colors as design tokens with semantic names: `--color-surface`, `--color-text-primary`, `--color-accent`
+- Every color needs **4.5:1 contrast ratio** minimum (WCAG AA) for text
+- Non-text elements need **3:1** minimum
+- Never rely on color alone to convey information — pair with icons, text, or patterns
+- Test with color blindness simulators
+
+### Dark Mode
+- Detect system preference with `prefers-color-scheme`
+- Don't just invert — re-design surfaces: dark surfaces get lighter elevation, reduce saturation
+- Smooth transition between modes (CSS transitions on `background-color`, `color`)
+- Diagrams/images: consider `filter: invert(1)` or provide alternate assets
+- Store user preference and sync with system default
+
+## Layout & Spacing
+
+### Grid System
+- Use an **8px base grid** — all spacing is a multiple of 8 (4px for tight spaces)
+- CSS Grid for 2D layouts, Flexbox for 1D alignment
+- Consistent spacing tokens: `--space-xs: 4px`, `--space-sm: 8px`, `--space-md: 16px`, `--space-lg: 24px`, `--space-xl: 32px`, `--space-2xl: 48px`, `--space-3xl: 64px`
+
+### Responsive Design
+- **Mobile-first**: design for 320px, scale up
+- Breakpoints: only add when the layout breaks, not at device widths
+- Use `container queries` for component-level responsiveness
+- Fluid layouts with `minmax()`, `auto-fill`, `auto-fit`
+- Every interactive target: minimum **44×44px** touch area (WCAG 2.5.5)
+
+### Rules
+- Use consistent gutters — don't mix random padding values
+- Stacking: define a z-index scale (e.g., base: 0, dropdown: 100, modal: 200, toast: 300)
+- Avoid magic numbers — extract to named tokens
+
+## Motion & Animation
+
+### Principles
+- **Purpose before polish** — every animation must serve a purpose: orientation, feedback, continuity, or delight
+- **Spring physics** over linear easing — use `cubic-bezier(0.175, 0.885, 0.32, 1.275)` or spring-based libraries
+- Duration budget: micro-interactions **100-200ms**, transitions **200-400ms**, page transitions **300-500ms**
+- Never exceed **500ms** unless it's a storytelling/onboarding animation
+
+### Performance
+- Animate only `transform` and `opacity` — these run on the compositor thread
+- Never animate `width`, `height`, `top`, `left`, `margin`, `padding` (trigger layout)
+- Use `will-change` sparingly and only before the animation starts
+- `requestAnimationFrame` for JS animations
+
+### Accessibility
+- **Always respect `prefers-reduced-motion`**: reduce or remove animations when set
+- Layout animations: use `layout` prop (Framer Motion) or FLIP technique
+- Skeleton screens during loading — never an empty blank page
+- Skeleton loading → content: smooth fade transition, not a hard swap
+
+### Patterns
+- Enter/exit transitions with stagger for lists
+- Shared element transitions between route changes
+- Micro-interactions on hover/focus: subtle scale, bg-color shift, shadow change
+- Pull-to-refresh, swipe gestures (mobile) with physics-based feel
+
+## Accessibility (WCAG AA Mandatory)
+
+### Structure
+- Use **semantic HTML**: `header`, `nav`, `main`, `section`, `article`, `aside`, `footer`
+- Every `<img>` has a meaningful `alt` (or `alt=""` for decorative)
+- Every form field has a visible `<label>` (not just placeholder)
+- Headings form a logical hierarchy (`h1` → `h2` → `h3`, no skipping)
+
+### Keyboard Navigation
+- All interactive elements reachable via **Tab** key
+- Logical tab order (follows visual reading order)
+- Focus indicators: visible, high-contrast, never `outline: none` without replacement
+- Escape to close modals/dropdowns, Enter/Space to activate
+- Skip-to-content link for screen readers
+
+### Screen Readers
+- ARIA labels on icons-only buttons: `aria-label="Close"`
+- Live regions for dynamic content: `aria-live="polite"` for updates, `"assertive"` for errors
+- Landmark roles if semantic HTML is insufficient
+- Don't use ARIA when a native HTML element works (`<button>` not `<div role="button">`)
+
+### Testing
+- Tab through entire flow without mouse
+- Test with screen reader (NVDA, VoiceOver)
+- Run Lighthouse accessibility audit
+- Test at 200% zoom — nothing should break or overflow
+
+## Forms
+
+- **Instant inline validation** — validate on blur, not on every keystroke
+- Show error messages below the field, not in an alert
+- Preserve user input on error — never clear a form on submit failure
+- **Auto-save** drafts for long forms (debounced)
+- Use `inputmode` for mobile: `numeric`, `email`, `tel`, `url`
+- Multi-step forms: show progress indicator and allow back-navigation
+- File uploads: drag-and-drop zone, progress indicator, file type restrictions, preview
+- **Optimistic UI**: show success immediately, revert on error
+
+## Navigation & State
+
+- URL should always reflect application state (`/settings/profile` not `/settings#profile`)
+- Support deep linking — any URL should be shareable and land on the right view
+- Breadcrumbs for hierarchical navigation (3+ levels deep)
+- Keyboard shortcuts for power users (document them)
+- Browser back/forward must work correctly — don't break history
+
+## Performance
+
+- **Virtual scroll** for lists > 100 items — don't render 10,000 DOM nodes
+- **Lazy load** images: use `loading="lazy"`, provide dimensions to prevent layout shift
+- **Prefetch** next-likely routes on hover/viewport intersection
+- **Code split** by route — each page only loads its own JavaScript
+- **Edge rendering** — render at the CDN edge when possible (SSR, RSC)
+- Optimize images: use `<picture>` with WebP/AVIF + fallback
+- Font loading: `font-display: swap`, preload critical fonts
+- Target LCP < 2.5s, INP < 200ms, CLS < 0.1
+
+## Error Handling
+
+- **Graceful degradation** — partial failures shouldn't crash the entire page
+- Show retry buttons on transient errors
+- Offline indicator when network is lost
+- Clear error messages: what happened, what the user can do about it
+- Error boundaries in React: catch rendering errors, show fallback UI
+- Never show raw error messages, stack traces, or error codes to users
+
+## SSR & Hydration
+
+- Prevent hydration mismatches: no `Date.now()`, `Math.random()`, `window` in server render
+- Use streaming SSR for faster TTFB
+- Optimistic mutations: update UI before server confirms
+- Handle loading states with Suspense boundaries
+
+## Internationalization (i18n)
+
+- **RTL support**: use logical properties (`margin-inline-start` not `margin-left`)
+- Format dates/numbers/currencies locale-aware — never hardcode formats
+- Text expansion room: German/French can be 50%+ longer than English
+- Unicode support: test with CJK, Arabic, emoji
+- Externalize all user-visible strings
+
+## AI Slop Test — MANDATORY CHECK
+
+Before shipping ANY design, verify it does NOT have these AI-generated tells:
+
+| AI Slop Pattern | What to check |
+|-----------------|---------------|
+| Centered hero + gradient blob | Does it look like every AI demo landing page? ADD ASYMMETRY |
+| Lowercase geometric sans headings | Add personality: case choices, weight variation, size contrast |
+| Purple-to-blue gradient | If using gradients, use brand-specific or creative color stops |
+| Uniform card grid with icon + heading + text | Vary card sizes, add imagery, break the grid |
+| Stock illustration style | Use real photos, custom illustrations, or no imagery |
+| "Modern SaaS template" look | Add something unexpected: editorial layout, bold typography, color blocking |
+| Generic placeholder copy | Real content or clearly marked FPO (For Placement Only) |
+| Identical padding everywhere | Vary rhythm — tight grouping inside sections, generous between |
+| No texture or depth | Add subtle noise, shadows, borders, layering |
+| Perfectly symmetrical everything | Break symmetry deliberately — offset grids, varied alignments |
+
+If 3+ items match → **STOP and redesign**. The goal is distinctive, not generic.
+
+## Implementation Principles
+
+1. **Design tokens before code** — define variables/tokens first, then use them everywhere
+2. **Component boundaries** — each component owns its internal layout, parent owns its placement
+3. **Progressive enhancement** — works without JS, enhanced with JS
+4. **Content-first** — design with real content, not lorem ipsum
+5. **Test in context** — view components inside the actual page, not just in isolation