mandrel 1.93.0 → 2.0.0

package/.agents/skills/core/epic-plan-spec-author/examples.md

@@ -1,91 +0,0 @@
-# epic-plan-spec-author — examples & extended rationale
-
-Read this file on demand while authoring the Tech Spec. The SKILL.md carries
-the operating contract (Policy Capsule, Inputs / Outputs, Procedure, the two
-authoritative system prompts, and Constraints); this file carries the worked
-Delivery Slicing example and the extended rationale behind the slicing rules.
-
-## Delivery Slicing — extended rationale
-
-The Tech Spec MUST carry a `## Delivery Slicing` section in which the Architect
-— who holds the full design — proposes how the Epic's enumerated capabilities
-**cluster into N shippable Stories**. This section is the intentional grouping
-the Phase 8 consolidation pass
-([`epic-plan-consolidate`](../epic-plan-consolidate/SKILL.md)) reconciles the
-decomposer's draft against before any GitHub write. Without it, the decompose
-phase maps Epic capabilities to Stories ~1:1 and cannot produce a coarser,
-holistic plan; with it, the consolidation critic has a well-defined reference
-instead of a guess.
-
-**The proposed count is a ceiling, not a target.** Consolidation reconciles
-the draft *toward* your grouping, but it treats the count as an upper bound: it
-may **merge below** your proposed count when slices form dependent
-single-consumer chains, and it **never splits above** it. Over-slicing here
-therefore locks in fragmentation only when the extra slices are genuinely
-independent — so keep a slice separate only when it earns its own delivery
-session.
-
-**Write the Delivery Slicing section before any other section — it is the
-primary input to Phase 8 consolidation.** Author it first so the rest of the
-spec (Core Components, API Changes, Data Models) hangs off a deliberate
-slicing decision rather than being reverse-engineered into one at the end.
-Drafting it last is exactly how the model omits it under the weight of the
-other sections.
-
-Author the section as a table — one row per proposed slice — naming the
-capability cluster each slice would deliver, what ships in it, and whether it
-can ship independently. Use **noun phrases** for slice names ("Foundation",
-"Transport seam", "Send helper") so they map cleanly onto Feature titles in the
-resulting decomposition — never verb phrases ("Add transport") or file names
-("`sender.ts`"). Do **not** coarsen the Epic's capability enumeration to produce
-the slicing: the granularity lever is *this* grouping recommendation, not a
-dumbed-down Epic enumeration.
-
-**What "Independent?" means:** can this slice ship to production and provide
-value *without the next slice landing*? A `Yes` slice is releasable on its own;
-a `No` slice only becomes valuable once a later slice lands on top of it.
-
-**"Independent? No" is a smell that must be justified.** A dependent,
-single-consumer slice (one that only feeds the next slice) folds into its
-consumer by default — it is not worth its own delivery session's hydration,
-branch, PR, and CI ceremony. Mark a slice `No` only when you can name a
-one-line reason to keep it separate anyway: **parallelism** (two `No` slices
-that can be delivered concurrently by different sessions), **risk isolation**
-(a blast-radius or reviewability reason to land it as its own reviewable PR),
-or **delivery-envelope pressure** (folding it in would push the consumer past a
-single-session sizing envelope). Absent such a justification, do not author the
-slice as its own row — fold it into its consumer and let the merged slice carry
-the combined capability.
-
-### Worked example
-
-```text
-## Delivery Slicing
-
-Proposed shippable slices (consolidation ceiling for Phase 8):
-
-| Slice          | What ships                                              | Independent? |
-| -------------- | ------------------------------------------------------ | ------------ |
-| Foundation     | Config schema, types, and the no-op default path       | Yes          |
-| Transport seam | The pluggable transport interface + in-memory adapter  | Yes          |
-| Send helper    | The send() helper + retries, built on the transport    | No (justified: risk isolation) |
-
-- **Foundation** folds Epic capabilities "config surface" + "type model" — they
-  share a reason to exist and ship as one reviewable PR.
-- **Transport seam** is the pluggable boundary; it provides value on its own
-  (in-memory adapter is usable for tests) so it is independently shippable.
-- **Send helper** depends on the transport seam landing first, so it is *not*
-  independent. It stays its own slice only because the retry/backoff logic is a
-  large, high-blast-radius surface worth isolating in its own reviewable PR
-  (risk isolation). Absent that justification it would fold into Transport
-  seam — a bare "depends on the previous slice" is not a reason to keep it
-  separate.
-```
-
-The consolidation pass degrades gracefully when this section is absent (it
-falls back to cohesion + single-Story-Feature rules only), so authoring it is
-how the Architect steers the decomposition toward fewer, right-sized Stories.
-Because the count is a **ceiling**, an over-sliced table is coarsened back
-during consolidation — but only where the extra slices are dependent
-single-consumer chains, so an unjustified `No` slice is the one you should fold
-in yourself rather than leaning on the consolidator to catch.

package/.agents/skills/core/frontend-ui-engineering/SKILL.md

@@ -1,357 +0,0 @@
----
-name: frontend-ui-engineering
-description:
-  Builds production-quality UIs. Use when building or modifying user-facing
-  interfaces. Use when creating components, implementing layouts, managing
-  state, or when the output needs to look and feel production-quality rather
-  than AI-generated.
----
-
-# Frontend UI Engineering
-
-## Policy Capsule
-
-- Build UI that meets WCAG 2.1 AA: every interactive element keyboard-accessible, ARIA labels on icon-only controls, focus moved when content changes, color never the sole indicator of state.
-- Adhere to the project's design system — use semantic tokens (`text-primary`, `bg-surface`) and the spacing scale (no arbitrary pixel values, no inline styles).
-- Avoid the "AI aesthetic": no default purple/indigo palettes, gratuitous gradients, blanket `rounded-2xl`, oversized padding, or shadow-heavy layering.
-- Prefer composition over configuration; keep components focused (split anything past ~200 lines) and separate data-fetching containers from presentation components.
-- Choose the simplest state mechanism that works: local `useState` → lifted state → context (read-heavy) → URL state → server-state library → global store; do not prop-drill past three levels.
-- Render meaningful loading, empty, and error states for every async surface — skeletons for content (not spinners), and explicit empty-state copy + CTA.
-- Design mobile-first and verify at 320 / 768 / 1024 / 1440 px breakpoints before claiming responsive.
-- Respect the heading hierarchy (one `h1` per page, no skipped levels) and never re-purpose heading styles for non-heading content.
-- Verify accessibility tooling (axe-core / dev-tools warnings) is clean and a screen reader can convey the page structure before marking the work done.
-
-## Overview
-
-Build production-quality user interfaces that are accessible, performant, and
-visually polished. The goal is UI that looks like it was built by a design-aware
-engineer at a top company — not like it was generated by an AI. This means real
-design system adherence, proper accessibility, thoughtful interaction patterns,
-and no generic "AI aesthetic."
-
-## When to Use
-
-- Building new UI components or pages
-- Modifying existing user-facing interfaces
-- Implementing responsive layouts
-- Adding interactivity or state management
-- Fixing visual or UX issues
-
-## Component Architecture
-
-### File Structure
-
-Colocate everything related to a component:
-
-```text
-src/components/
-  TaskList/
-    TaskList.tsx          # Component implementation
-    TaskList.test.tsx     # Tests
-    TaskList.stories.tsx  # Storybook stories (if using)
-    use-task-list.ts      # Custom hook (if complex state)
-    types.ts              # Component-specific types (if needed)
-```
-
-### Component Patterns
-
-**Prefer composition over configuration:**
-
-```tsx
-// Good: Composable
-<Card>
-  <CardHeader>
-    <CardTitle>Tasks</CardTitle>
-  </CardHeader>
-  <CardBody>
-    <TaskList tasks={tasks} />
-  </CardBody>
-</Card>
-
-// Avoid: Over-configured
-<Card
-  title="Tasks"
-  headerVariant="large"
-  bodyPadding="md"
-  content={<TaskList tasks={tasks} />}
-/>
-```
-
-**Keep components focused:**
-
-```tsx
-// Good: Does one thing
-export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
-  return (
-    <li className="flex items-center gap-3 p-3">
-      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
-      <span className={task.done ? 'line-through text-muted' : ''}>
-        {task.title}
-      </span>
-      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
-        <TrashIcon />
-      </Button>
-    </li>
-  );
-}
-```
-
-**Separate data fetching from presentation:**
-
-```tsx
-// Container: handles data
-export function TaskListContainer() {
-  const { tasks, isLoading, error } = useTasks();
-
-  if (isLoading) return <TaskListSkeleton />;
-  if (error)
-    return <ErrorState message="Failed to load tasks" retry={refetch} />;
-  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;
-
-  return <TaskList tasks={tasks} />;
-}
-
-// Presentation: handles rendering
-export function TaskList({ tasks }: { tasks: Task[] }) {
-  return (
-    <ul role="list" className="divide-y">
-      {tasks.map((task) => (
-        <TaskItem key={task.id} task={task} />
-      ))}
-    </ul>
-  );
-}
-```
-
-## State Management
-
-**Choose the simplest approach that works:**
-
-```text
-Local state (useState)           → Component-specific UI state
-Lifted state                     → Shared between 2-3 sibling components
-Context                          → Theme, auth, locale (read-heavy, write-rare)
-URL state (searchParams)         → Filters, pagination, shareable UI state
-Server state (React Query, SWR)  → Remote data with caching
-Global store (Zustand, Redux)    → Complex client state shared app-wide
-```
-
-**Avoid prop drilling deeper than 3 levels.** If you're passing props through
-components that don't use them, introduce context or restructure the component
-tree.
-
-## Design System Adherence
-
-### Avoid the AI Aesthetic
-
-AI-generated UI has recognizable patterns. Avoid all of them:
-
-| AI Default                       | Why It Is a Problem                                                                           | Production Quality                                      |
-| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| Purple/indigo everything         | Models default to visually "safe" palettes, making every app look identical                   | Use the project's actual color palette                  |
-| Excessive gradients              | Gradients add visual noise and clash with most design systems                                 | Flat or subtle gradients matching the design system     |
-| Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system         |
-| Generic hero sections            | Template-driven layout with no connection to the actual content or user need                  | Content-first layouts                                   |
-| Lorem ipsum-style copy           | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content                           |
-| Oversized padding everywhere     | Equal generous padding destroys visual hierarchy and wastes screen space                      | Consistent spacing scale                                |
-| Stock card grids                 | Uniform grids are a layout shortcut that ignores information priority and scanning patterns   | Purpose-driven layouts                                  |
-| Shadow-heavy design              | Layered shadows add depth that competes with content and slows rendering on low-end devices   | Subtle or no shadows unless the design system specifies |
-
-### Spacing and Layout
-
-Use a consistent spacing scale. Don't invent values:
-
-```css
-/* Use the scale: 0.25rem increments (or whatever the project uses) */
-/* Good */
-padding: 1rem; /* 16px */
-/* Good */
-gap: 0.75rem; /* 12px */
-/* Bad */
-padding: 13px; /* Not on any scale */
-/* Bad */
-margin-top: 2.3rem; /* Not on any scale */
-```
-
-### Typography
-
-Respect the type hierarchy:
-
-```text
-h1 → Page title (one per page)
-h2 → Section title
-h3 → Subsection title
-body → Default text
-small → Secondary/helper text
-```
-
-Don't skip heading levels. Don't use heading styles for non-heading content.
-
-### Color
-
-- Use semantic color tokens: `text-primary`, `bg-surface`, `border-default` —
-  not raw hex values
-- Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
-- Don't rely solely on color to convey information (use icons, text, or patterns
-  too)
-
-## Accessibility (WCAG 2.1 AA)
-
-Every component must meet these standards:
-
-### Keyboard Navigation
-
-```tsx
-// Every interactive element must be keyboard accessible
-<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
-<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
-<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
-     onKeyDown={e => e.key === 'Enter' && handleClick()}>
-  Click me
-</div>
-```
-
-### ARIA Labels
-
-```tsx
-// Label interactive elements that lack visible text
-<button aria-label="Close dialog"><XIcon /></button>
-
-// Label form inputs
-<label htmlFor="email">Email</label>
-<input id="email" type="email" />
-
-// Or use aria-label when no visible label exists
-<input aria-label="Search tasks" type="search" />
-```
-
-### Focus Management
-
-```tsx
-// Move focus when content changes
-function Dialog({ isOpen, onClose }: DialogProps) {
-  const closeRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    if (isOpen) closeRef.current?.focus();
-  }, [isOpen]);
-
-  // Trap focus inside dialog when open
-  return (
-    <dialog open={isOpen}>
-      <button ref={closeRef} onClick={onClose}>
-        Close
-      </button>
-      {/* dialog content */}
-    </dialog>
-  );
-}
-```
-
-### Meaningful Empty and Error States
-
-```tsx
-// Don't show blank screens
-function TaskList({ tasks }: { tasks: Task[] }) {
-  if (tasks.length === 0) {
-    return (
-      <div role="status" className="text-center py-12">
-        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
-        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
-        <p className="mt-1 text-sm text-muted">
-          Get started by creating a new task.
-        </p>
-        <Button className="mt-4" onClick={onCreateTask}>
-          Create Task
-        </Button>
-      </div>
-    );
-  }
-
-  return <ul role="list">...</ul>;
-}
-```
-
-## Responsive Design
-
-Design for mobile first, then expand:
-
-```tsx
-// Tailwind: mobile-first responsive
-<div className="
-  grid grid-cols-1      /* Mobile: single column */
-  sm:grid-cols-2        /* Small: 2 columns */
-  lg:grid-cols-3        /* Large: 3 columns */
-  gap-4
-">
-```
-
-Test at these breakpoints: 320px, 768px, 1024px, 1440px.
-
-## Loading and Transitions
-
-```tsx
-// Skeleton loading (not spinners for content)
-function TaskListSkeleton() {
-  return (
-    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
-      {Array.from({ length: 3 }).map((_, i) => (
-        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
-      ))}
-    </div>
-  );
-}
-
-// Optimistic updates for perceived speed
-function useToggleTask() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: toggleTask,
-    onMutate: async (taskId) => {
-      await queryClient.cancelQueries({ queryKey: ['tasks'] });
-      const previous = queryClient.getQueryData(['tasks']);
-
-      queryClient.setQueryData(['tasks'], (old: Task[]) =>
-        old.map((t) => (t.id === taskId ? { ...t, done: !t.done } : t)),
-      );
-
-      return { previous };
-    },
-    onError: (_err, _taskId, context) => {
-      queryClient.setQueryData(['tasks'], context?.previous);
-    },
-  });
-}
-```
-
-## Common Rationalizations
-
-| Rationalization                                | Reality                                                                                      |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| "Accessibility is a nice-to-have"              | It's a legal requirement in many jurisdictions and an engineering quality standard.          |
-| "We'll make it responsive later"               | Retrofitting responsive design is 3x harder than building it from the start.                 |
-| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression for reviewers. |
-| "This is just a prototype"                     | Prototypes become production code. Build the foundation right.                               |
-| "The AI aesthetic is fine for now"             | It signals low quality. Use the project's actual design system from the start.               |
-
-## Red Flags
-
-- Components with more than 200 lines (split them)
-- Inline styles or arbitrary pixel values
-- Missing error states, loading states, or empty states
-- No keyboard navigation testing
-- Color as the sole indicator of state (red/green without text or icons)
-- Generic "AI look" (purple gradients, oversized cards, stock layouts)
-
-## Verification
-
-After building UI:
-
-- [ ] Component renders without console errors
-- [ ] All interactive elements are keyboard accessible (Tab through the page)
-- [ ] Screen reader can convey the page's content and structure
-- [ ] Responsive: works at 320px, 768px, 1024px, 1440px
-- [ ] Loading, error, and empty states all handled
-- [ ] Follows the project's design system (spacing, colors, typography)
-- [ ] No accessibility warnings in dev tools or axe-core

package/.agents/skills/core/hydrate-context/SKILL.md

@@ -1,123 +0,0 @@
----
-name: hydrate-context
-description: >-
-  Hydrate a Story ticket into a structured ContextEnvelope (or the
-  legacy `{ prompt }` stdout wrapper). Reads the ticket body, resolves the
-  parent Epic, embeds the sectioned Epic body (acceptance-table section
-  stripped), and assembles
-  named sections with provenance and section-aware elision. Successor to
-  the retired mandrel MCP `context.hydrate` tool.
-allowed_tools:
-  - Read
-  - Bash
----
-
-# hydrate-context
-
-## Policy Capsule
-
-- Invoke via `node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]`; the wrapping CLI is the only supported entry point and delegates to `lib/orchestration/context-hydration-engine.js`.
-- Treat the operation as strictly **read-only on GitHub** — never modify ticket bodies, never post comments, never apply labels.
-- When `--epic` is omitted, parse the Epic ID from the ticket body's `Epic: #N` line; do not infer it from elsewhere.
-- Surface `persona::*` and `skill::*` labels from the ticket into the composed prompt so the downstream executor can pin its sub-agent dispatch.
-- Emit exactly one JSON object on stdout (`{ "prompt": "..." }` by default, or `{ "envelope": {...} }` with `--emit envelope`) and nothing else — no temp files, no diagnostic prints that would corrupt the envelope.
-- Honour the engine's context-budget cap via section-aware elision (`elideEnvelope`): lower-priority sections drop or summarize before higher-priority ones. Never silently truncate mid-string.
-- Do not persist the composed prompt to disk; forwarding is the caller's responsibility.
-
-## Role
-
-Context aggregator. Resolves a ticket's hierarchy (Story → Epic)
-and stitches the Epic body — the single planning document, carrying the
-folded Tech Spec sections — plus the Story body into a
-single prompt the executor consumes. The Epic body is embedded with its
-`## Acceptance Table` managed section stripped (close-time reconciliation
-detail the executor does not need); there is no separate Tech Spec fetch
-(Story #4324).
-
-## When to use
-
-Whenever an Epic-scoped sub-agent needs the same context bundle the
-human operator would assemble manually before opening the file editor.
-The wrapping script `hydrate-context.js` is the CLI today; this Skill
-documents the dispatch contract for callers that want to invoke via
-the Skill tool.
-
-## Inputs
-
-- `--ticket <id>` — GitHub issue number to hydrate (required).
-- `--epic <id>` (optional) — when omitted, parsed from the ticket
-  body's `Epic: #N` line.
-
-Persona and skill labels are read off the ticket
-(`persona::*`, `skill::*`) and surfaced in the composed prompt so the
-executor can pin its sub-agent dispatch.
-
-## Outputs
-
-The engine assembles a typed **ContextEnvelope** (`lib/orchestration/context-envelope.js`) and serializes it for consumers:
-
-| Field | Role |
-| --- | --- |
-| `schemaVersion` | Always `"1"` for the current contract. |
-| `task` | `{ id, title, persona?, skills?, protocolVersion? }` from the ticket and labels. |
-| `sections[]` | Named blocks (`protocolPolicy`, `persona`, `skillCapsules`, `hierarchy`, `acceptanceCriteria`, `verificationCommands`, `taskInstructions`) each with `priority`, `elideWhenOverBudget` (`drop` \| `summarize`), `content`, `estimatedTokens`, optional `source`. |
-| `provenance[]` | Ticket snapshots: `{ id, version, hash, retrievedAt }` so auditors can cite what was fetched. |
-| `budget` | `{ maxTokens, used, elided[] }` after `elideEnvelope` runs. |
-| `warnings[]` | Non-fatal hydration notices (missing files, skipped skills, etc.). |
-
-Default CLI stdout (backward-compatible wrapper):
-
-```json
-{ "prompt": "..." }
-```
-
-`prompt` is `envelopeToPrompt(envelope)` — sections joined in `SECTION_RENDER_ORDER`, not elision priority. For inspection or downstream tools that consume the typed shape:
-
-```bash
-node .agents/scripts/hydrate-context.js --ticket <id> --emit envelope
-```
-
-```json
-{ "envelope": { "schemaVersion": "1", "task": { ... }, "sections": [ ... ], "provenance": [ ... ], "budget": { ... }, "warnings": [ ... ] } }
-```
-
-The Skill writes nothing else — no GitHub comments, no temp files.
-Idempotence is trivial because the operation is read-only.
-
-## Procedure
-
-```bash
-node .agents/scripts/hydrate-context.js --ticket <id> [--epic <id>]
-```
-
-Delegates to `hydrateContext` from
-`lib/orchestration/context-hydration-engine.js`. The engine handles
-provider I/O, body parsing, provenance stamping, and
-`elideEnvelope` when `budget.used` exceeds `limits.maxTokenBudget`.
-
-**Section-aware elision.** Each section carries a numeric `priority`
-(lower drops first) and an `elideWhenOverBudget` policy (`drop` removes
-the section; `summarize` keeps a head excerpt). Defaults live in
-`DEFAULT_SECTION_PRIORITIES` and `DEFAULT_ELIDE_POLICIES` in
-`context-envelope.js`. Elided section names are recorded in
-`budget.elided`.
-
-**Capsule-only skill loading.** Activated skills resolve through
-`skills.index.json` and `loadSkillCapsule`, emitting only the Policy
-Capsule (the skill's non-negotiables) plus a pointer instruction into the
-`skillCapsules` section. Full `SKILL.md` bodies are never inlined into a
-task prompt — the sub-agent reads the full playbook on demand via the
-rendered `Read <path>` pointer. The full-body injection path, the
-`fullSkillBodies` config flag, and the `skill::full` label were removed in
-a hard cutover (Story #3863); the only residual full-body emission is the
-defensive fallback when a `SKILL.md` is missing its capsule marker (a
-malformed manifest), which also logs a warning.
-
-## Constraints
-
-- Do **not** modify ticket bodies or post comments. The Skill is
-  strictly read-only on GitHub.
-- Do **not** persist the composed prompt to disk. The caller is
-  responsible for forwarding the stdout envelope to its consumer.
-- Do **not** bypass the context-budget cap — honour `elideEnvelope`
-  and the per-section policies; never silently truncate.