mandrel 1.57.0

package/.agents/skills/core/shipping-and-launch/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: shipping-and-launch
+description:
+  Prepares production launches. Use when preparing to deploy to production. Use
+  when you need a pre-launch checklist, when setting up monitoring, when
+  planning a staged rollout, or when you need a rollback strategy.
+---
+
+# Shipping and Launch
+
+## Policy Capsule
+
+- Every launch MUST be reversible, observable, and incremental — no big-bang deploys, no Friday-afternoon ships.
+- Walk the pre-launch checklist top to bottom: code quality, security, performance, accessibility, infrastructure, documentation. A red box blocks the deploy.
+- Ship behind feature flags so deployment is decoupled from release. Every flag has a named owner, a recorded expiration date, and gets cleaned up within 2 weeks of full rollout.
+- Follow the staged rollout sequence: staging → production (flag off) → team (flag on) → 5 % canary → 25 % → 50 % → 100 %. Advance only when error rate, p95 latency, client JS errors, and business metrics are all within the green thresholds for the prior stage.
+- Roll back **immediately** when error rate exceeds 2× baseline, p95 latency rises by more than 50 %, user-reported issues spike, data integrity is at risk, or a security vulnerability surfaces.
+- Document a rollback plan **before** the deploy: explicit trigger conditions, step-by-step revert procedure, database migration rollback notes, and target time-to-rollback.
+- Monitor the right surfaces: application metrics (error rate, p50/p95/p99, request volume), infrastructure (CPU, memory, DB pool), client (Core Web Vitals, JS errors), and key business metrics.
+- Wire error reporting through a tracking service (with user/request context) on both client and server; never leak stack traces or internal error details in API responses.
+- Perform first-hour post-launch verification: health endpoint 200, no new error types, latency stable, critical user flow exercised manually, logs flowing, rollback mechanism dry-run.
+
+## Overview
+
+Ship with confidence. The goal is not just to deploy — it's to deploy safely,
+with monitoring in place, a rollback plan ready, and a clear understanding of
+what success looks like. Every launch should be reversible, observable, and
+incremental.
+
+## When to Use
+
+- Deploying a feature to production for the first time
+- Releasing a significant change to users
+- Migrating data or infrastructure
+- Opening a beta or early access program
+- Any deployment that carries risk (all of them)
+
+## The Pre-Launch Checklist
+
+### Code Quality
+
+- [ ] All tests pass (unit, integration, e2e)
+- [ ] Build succeeds with no warnings
+- [ ] Lint and type checking pass
+- [ ] Code reviewed and approved
+- [ ] No TODO comments that should be resolved before launch
+- [ ] No `console.log` debugging statements in production code
+- [ ] Error handling covers expected failure modes
+
+### Security
+
+- [ ] No secrets in code or version control
+- [ ] `npm audit` shows no critical or high vulnerabilities
+- [ ] Input validation on all user-facing endpoints
+- [ ] Authentication and authorization checks in place
+- [ ] Security headers configured (CSP, HSTS, etc.)
+- [ ] Rate limiting on authentication endpoints
+- [ ] CORS configured to specific origins (not wildcard)
+
+### Performance
+
+- [ ] Core Web Vitals within "Good" thresholds
+- [ ] No N+1 queries in critical paths
+- [ ] Images optimized (compression, responsive sizes, lazy loading)
+- [ ] Bundle size within budget
+- [ ] Database queries have appropriate indexes
+- [ ] Caching configured for static assets and repeated queries
+
+### Accessibility
+
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] Screen reader can convey page content and structure
+- [ ] Color contrast meets WCAG 2.1 AA (4.5:1 for text)
+- [ ] Focus management correct for modals and dynamic content
+- [ ] Error messages are descriptive and associated with form fields
+- [ ] No accessibility warnings in axe-core or Lighthouse
+
+### Infrastructure
+
+- [ ] Environment variables set in production
+- [ ] Database migrations applied (or ready to apply)
+- [ ] DNS and SSL configured
+- [ ] CDN configured for static assets
+- [ ] Logging and error reporting configured
+- [ ] Health check endpoint exists and responds
+
+### Documentation
+
+- [ ] README updated with any new setup requirements
+- [ ] API documentation current
+- [ ] ADRs written for any architectural decisions
+- [ ] Changelog updated
+- [ ] User-facing documentation updated (if applicable)
+
+## Feature Flag Strategy
+
+Ship behind feature flags to decouple deployment from release:
+
+```typescript
+// Feature flag check
+const flags = await getFeatureFlags(userId);
+
+if (flags.taskSharing) {
+  // New feature: task sharing
+  return <TaskSharingPanel task={task} />;
+}
+
+// Default: existing behavior
+return null;
+```
+
+**Feature flag lifecycle:**
+
+```text
+1. DEPLOY with flag OFF     → Code is in production but inactive
+2. ENABLE for team/beta     → Internal testing in production environment
+3. GRADUAL ROLLOUT          → 5% → 25% → 50% → 100% of users
+4. MONITOR at each stage    → Watch error rates, performance, user feedback
+5. CLEAN UP                 → Remove flag and dead code path after full rollout
+```
+
+**Rules:**
+
+- Every feature flag has an owner and an expiration date
+- Clean up flags within 2 weeks of full rollout
+- Don't nest feature flags (creates exponential combinations)
+- Test both flag states (on and off) in CI
+
+## Staged Rollout
+
+### The Rollout Sequence
+
+```text
+1. DEPLOY to staging
+   └── Full test suite in staging environment
+   └── Manual smoke test of critical flows
+
+2. DEPLOY to production (feature flag OFF)
+   └── Verify deployment succeeded (health check)
+   └── Check error monitoring (no new errors)
+
+3. ENABLE for team (flag ON for internal users)
+   └── Team uses the feature in production
+   └── 24-hour monitoring window
+
+4. CANARY rollout (flag ON for 5% of users)
+   └── Monitor error rates, latency, user behavior
+   └── Compare metrics: canary vs. baseline
+   └── 24-48 hour monitoring window
+   └── Advance only if all thresholds pass (see table below)
+
+5. GRADUAL increase (25% -> 50% -> 100%)
+   └── Same monitoring at each step
+   └── Ability to roll back to previous percentage at any point
+
+6. FULL rollout (flag ON for all users)
+   └── Monitor for 1 week
+   └── Clean up feature flag
+```
+
+### Rollout Decision Thresholds
+
+Use these thresholds to decide whether to advance, hold, or roll back at each
+stage:
+
+| Metric           | Advance (green)        | Hold and investigate (yellow)   | Roll back (red)                 |
+| ---------------- | ---------------------- | ------------------------------- | ------------------------------- |
+| Error rate       | Within 10% of baseline | 10-100% above baseline          | >2x baseline                    |
+| P95 latency      | Within 20% of baseline | 20-50% above baseline           | >50% above baseline             |
+| Client JS errors | No new error types     | New errors at <0.1% of sessions | New errors at >0.1% of sessions |
+| Business metrics | Neutral or positive    | Decline <5% (may be noise)      | Decline >5%                     |
+
+### When to Roll Back
+
+Roll back immediately if:
+
+- Error rate increases by more than 2x baseline
+- P95 latency increases by more than 50%
+- User-reported issues spike
+- Data integrity issues detected
+- Security vulnerability discovered
+
+## Monitoring and Observability
+
+### What to Monitor
+
+```text
+Application metrics:
+├── Error rate (total and by endpoint)
+├── Response time (p50, p95, p99)
+├── Request volume
+├── Active users
+└── Key business metrics (conversion, engagement)
+
+Infrastructure metrics:
+├── CPU and memory utilization
+├── Database connection pool usage
+├── Disk space
+├── Network latency
+└── Queue depth (if applicable)
+
+Client metrics:
+├── Core Web Vitals (LCP, INP, CLS)
+├── JavaScript errors
+├── API error rates from client perspective
+└── Page load time
+```
+
+### Error Reporting
+
+```typescript
+// Set up error boundary with reporting
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    // Report to error tracking service
+    reportError(error, {
+      componentStack: info.componentStack,
+      userId: getCurrentUser()?.id,
+      page: window.location.pathname,
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
+    }
+    return this.props.children;
+  }
+}
+
+// Server-side error reporting
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  reportError(err, {
+    method: req.method,
+    url: req.url,
+    userId: req.user?.id,
+  });
+
+  // Don't expose internals to users
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  });
+});
+```
+
+### Post-Launch Verification
+
+In the first hour after launch:
+
+```text
+1. Check health endpoint returns 200
+2. Check error monitoring dashboard (no new error types)
+3. Check latency dashboard (no regression)
+4. Test the critical user flow manually
+5. Verify logs are flowing and readable
+6. Confirm rollback mechanism works (dry run if possible)
+```
+
+## Rollback Strategy
+
+Every deployment needs a rollback plan before it happens:
+
+```markdown
+## Rollback Plan for [Feature/Release]
+
+### Trigger Conditions
+
+- Error rate > 2x baseline
+- P95 latency > [X]ms
+- User reports of [specific issue]
+
+### Rollback Steps
+
+1. Disable feature flag (if applicable) OR
+1. Deploy previous version: `git revert <commit> && git push`
+1. Verify rollback: health check, error monitoring
+1. Communicate: notify team of rollback
+
+### Database Considerations
+
+- Migration [X] has a rollback: `npx prisma migrate rollback`
+- Data inserted by new feature: [preserved / cleaned up]
+
+### Time to Rollback
+
+- Feature flag: < 1 minute
+- Redeploy previous version: < 5 minutes
+- Database rollback: < 15 minutes
+```
+
+## Common Rationalizations
+
+| Rationalization                                 | Reality                                                                                       |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| "It works in staging, it'll work in production" | Production has different data, traffic patterns, and edge cases. Monitor after deploy.        |
+| "We don't need feature flags for this"          | Every feature benefits from a kill switch. Even "simple" changes can break things.            |
+| "Monitoring is overhead"                        | Not having monitoring means you discover problems from user complaints instead of dashboards. |
+| "We'll add monitoring later"                    | Add it before launch. You can't debug what you can't see.                                     |
+| "Rolling back is admitting failure"             | Rolling back is responsible engineering. Shipping a broken feature is the failure.            |
+
+## Red Flags
+
+- Deploying without a rollback plan
+- No monitoring or error reporting in production
+- Big-bang releases (everything at once, no staging)
+- Feature flags with no expiration or owner
+- No one monitoring the deploy for the first hour
+- Production environment configuration done by memory, not code
+- "It's Friday afternoon, let's ship it"
+
+## Verification
+
+Before deploying:
+
+- [ ] Pre-launch checklist completed (all sections green)
+- [ ] Feature flag configured (if applicable)
+- [ ] Rollback plan documented
+- [ ] Monitoring dashboards set up
+- [ ] Team notified of deployment
+
+After deploying:
+
+- [ ] Health check returns 200
+- [ ] Error rate is normal
+- [ ] Latency is normal
+- [ ] Critical user flow works
+- [ ] Logs are flowing
+- [ ] Rollback tested or verified ready

package/.agents/skills/core/spec-driven-development/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: spec-driven-development
+description:
+  Creates specs before coding. Use when starting a new project, feature, or
+  significant change and no specification exists yet. Use when requirements are
+  unclear, ambiguous, or only exist as a vague idea.
+---
+
+# Spec-Driven Development
+
+## Policy Capsule
+
+- Follow the gated workflow: **Specify → Plan → Tasks → Implement**. Never advance until the human has reviewed and approved the current phase.
+- Surface assumptions explicitly **before** writing spec content: list them as "ASSUMPTIONS I'M MAKING" and ask the human to correct them. Never silently fill in ambiguous requirements.
+- Reframe vague requirements (e.g. "make it faster") as specific, testable success criteria with numeric targets before accepting them as scope.
+- Phase 1 specs MUST cover all six core areas: **Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries**.
+- The Boundaries section is three-tier and mandatory: **Always do** / **Ask first** / **Never do**. Database schema changes, dependency additions, and CI changes default to "Ask first".
+- Provide commands as full executable strings (with flags), not just tool names; provide code style as a real snippet plus key conventions, not prose-only descriptions.
+- Phase 3 tasks each have explicit acceptance criteria, a verification step (test/build/manual), declared file scope (≤ ~5 files), and dependency-ordered sequencing.
+- Treat the spec as a **living document** — update it first when decisions or scope change, commit it to version control, and link the relevant section from each PR.
+- Do not start implementation until the spec has been reviewed, success criteria are specific and testable, boundaries are defined, and the spec lives in the repo.
+
+## Overview
+
+Write a structured specification before writing any code. The spec is the shared
+source of truth between you and the human engineer — it defines what we're
+building, why, and how we'll know it's done. Code without a spec is guessing.
+
+## When to Use
+
+- Starting a new project or feature
+- Requirements are ambiguous or incomplete
+- The change touches multiple files or modules
+- You're about to make an architectural decision
+- The task would take more than 30 minutes to implement
+
+**When NOT to use:** Single-line fixes, typo corrections, or changes where
+requirements are unambiguous and self-contained.
+
+## The Gated Workflow
+
+Spec-driven development has four phases. Do not advance to the next phase until
+the current one is validated.
+
+```text
+SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
+   │          │        │          │
+   ▼          ▼        ▼          ▼
+ Human      Human    Human      Human
+ reviews    reviews  reviews    reviews
+```
+
+### Phase 1: Specify
+
+Start with a high-level vision. Ask the human clarifying questions until
+requirements are concrete.
+
+**Surface assumptions immediately.** Before writing any spec content, list what
+you're assuming:
+
+```text
+ASSUMPTIONS I'M MAKING:
+1. This is a web application (not native mobile)
+2. Authentication uses session-based cookies (not JWT)
+3. The database is PostgreSQL (based on existing Prisma schema)
+4. We're targeting modern browsers only (no IE11)
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The spec's entire purpose is to
+surface misunderstandings _before_ code gets written — assumptions are the most
+dangerous form of misunderstanding.
+
+**Write a spec document covering these six core areas:**
+
+1. **Objective** — What are we building and why? Who is the user? What does
+   success look like?
+
+2. **Commands** — Full executable commands with flags, not just tool names.
+
+   ```text
+   Build: npm run build
+   Test: npm test -- --coverage
+   Lint: npm run lint --fix
+   Dev: npm run dev
+   ```
+
+3. **Project Structure** — Where source code lives, where tests go, where docs
+   belong.
+
+   ```text
+   src/           → Application source code
+   src/components → React components
+   src/lib        → Shared utilities
+   tests/         → Unit and integration tests
+   e2e/           → End-to-end tests
+   docs/          → Documentation
+   ```
+
+4. **Code Style** — One real code snippet showing your style beats three
+   paragraphs describing it. Include naming conventions, formatting rules, and
+   examples of good output.
+
+5. **Testing Strategy** — What framework, where tests live, coverage
+   expectations, which test levels for which concerns.
+
+6. **Boundaries** — Three-tier system:
+   - **Always do:** Run tests before commits, follow naming conventions,
+     validate inputs
+   - **Ask first:** Database schema changes, adding dependencies, changing CI
+     config
+   - **Never do:** Commit secrets, edit vendor directories, remove failing tests
+     without approval
+
+**Spec template:**
+
+```markdown
+# Spec: [Project/Feature Name]
+
+## Objective
+
+[What we're building and why. User stories or acceptance criteria.]
+
+## Tech Stack
+
+[Framework, language, key dependencies with versions]
+
+## Commands
+
+[Build, test, lint, dev — full commands]
+
+## Project Structure
+
+[Directory layout with descriptions]
+
+## Code Style
+
+[Example snippet + key conventions]
+
+## Testing Strategy
+
+[Framework, test locations, coverage requirements, test levels]
+
+## Boundaries
+
+- Always: [...]
+- Ask first: [...]
+- Never: [...]
+
+## Success Criteria
+
+[How we'll know this is done — specific, testable conditions]
+
+## Open Questions
+
+[Anything unresolved that needs human input]
+```
+
+**Reframe instructions as success criteria.** When receiving vague requirements,
+translate them into concrete conditions:
+
+```text
+REQUIREMENT: "Make the dashboard faster"
+
+REFRAMED SUCCESS CRITERIA:
+- Dashboard LCP < 2.5s on 4G connection
+- Initial data load completes in < 500ms
+- No layout shift during load (CLS < 0.1)
+→ Are these the right targets?
+```
+
+This lets you loop, retry, and problem-solve toward a clear goal rather than
+guessing what "faster" means.
+
+### Phase 2: Plan
+
+With the validated spec, generate a technical implementation plan:
+
+1. Identify the major components and their dependencies
+2. Determine the implementation order (what must be built first)
+3. Note risks and mitigation strategies
+4. Identify what can be built in parallel vs. what must be sequential
+5. Define verification checkpoints between phases
+
+The plan should be reviewable: the human should be able to read it and say "yes,
+that's the right approach" or "no, change X."
+
+### Phase 3: Tasks
+
+Break the plan into discrete, implementable tasks:
+
+- Each task should be completable in a single focused session
+- Each task has explicit acceptance criteria
+- Each task includes a verification step (test, build, manual check)
+- Tasks are ordered by dependency, not by perceived importance
+- No task should require changing more than ~5 files
+
+**Task template:**
+
+```markdown
+- [ ] Task: [Description]
+  - Acceptance: [What must be true when done]
+  - Verify: [How to confirm — test command, build, manual check]
+  - Files: [Which files will be touched]
+```
+
+### Phase 4: Implement
+
+Execute tasks one at a time following `incremental-implementation` and
+`test-driven-development` skills. Use `context-engineering` to load the right
+spec sections and source files at each step rather than flooding the agent with
+the entire spec.
+
+## Keeping the Spec Alive
+
+The spec is a living document, not a one-time artifact:
+
+- **Update when decisions change** — If you discover the data model needs to
+  change, update the spec first, then implement.
+- **Update when scope changes** — Features added or cut should be reflected in
+  the spec.
+- **Commit the spec** — The spec belongs in version control alongside the code.
+- **Reference the spec in PRs** — Link back to the spec section that each PR
+  implements.
+
+## Common Rationalizations
+
+| Rationalization                       | Reality                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| "This is simple, I don't need a spec" | Simple tasks don't need _long_ specs, but they still need acceptance criteria. A two-line spec is fine. |
+| "I'll write the spec after I code it" | That's documentation, not specification. The spec's value is in forcing clarity _before_ code.          |
+| "The spec will slow us down"          | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.         |
+| "Requirements will change anyway"     | That's why the spec is a living document. An outdated spec is still better than no spec.                |
+| "The user knows what they want"       | Even clear requests have implicit assumptions. The spec surfaces those assumptions.                     |
+
+## Red Flags
+
+- Starting to write code without any written requirements
+- Asking "should I just start building?" before clarifying what "done" means
+- Implementing features not mentioned in any spec or task list
+- Making architectural decisions without documenting them
+- Skipping the spec because "it's obvious what to build"
+
+## Verification
+
+Before proceeding to implementation, confirm:
+
+- [ ] The spec covers all six core areas
+- [ ] The human has reviewed and approved the spec
+- [ ] Success criteria are specific and testable
+- [ ] Boundaries (Always/Ask First/Never) are defined
+- [ ] The spec is saved to a file in the repository