npm - agentbrief - Versions diffs - 0.1.0 - Mend

agentbrief 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (137) hide show

package/LICENSE +21 -0
package/README.md +141 -0
package/briefs/code-reviewer/brief.yaml +8 -0
package/briefs/code-reviewer/knowledge/review-standards.md +32 -0
package/briefs/code-reviewer/personality.md +19 -0
package/briefs/code-reviewer/skills/architecture-review/SKILL.md +76 -0
package/briefs/code-reviewer/skills/review-process/SKILL.md +41 -0
package/briefs/code-reviewer/skills/verification/SKILL.md +47 -0
package/briefs/data-analyst/brief.yaml +8 -0
package/briefs/data-analyst/knowledge/metrics-reference.md +43 -0
package/briefs/data-analyst/personality.md +23 -0
package/briefs/data-analyst/skills/metrics-framework/SKILL.md +90 -0
package/briefs/data-analyst/skills/sql-query-builder/SKILL.md +115 -0
package/briefs/devops-sre/brief.yaml +12 -0
package/briefs/devops-sre/knowledge/runbook.md +69 -0
package/briefs/devops-sre/personality.md +18 -0
package/briefs/devops-sre/skills/ci-cd-github-actions/SKILL.md +114 -0
package/briefs/devops-sre/skills/monitoring-observability/SKILL.md +394 -0
package/briefs/devops-sre/skills/systematic-debugging/SKILL.md +46 -0
package/briefs/devops-sre/skills/verification/SKILL.md +47 -0
package/briefs/frontend-design/brief.yaml +8 -0
package/briefs/frontend-design/knowledge/design-principles.md +43 -0
package/briefs/frontend-design/personality.md +19 -0
package/briefs/frontend-design/skills/design-review-checklist/SKILL.md +151 -0
package/briefs/frontend-design/skills/web-design-guidelines/SKILL.md +39 -0
package/briefs/fullstack-dev/brief.yaml +9 -0
package/briefs/fullstack-dev/personality.md +18 -0
package/briefs/growth-engineer/brief.yaml +8 -0
package/briefs/growth-engineer/knowledge/growth-framework.md +83 -0
package/briefs/growth-engineer/personality.md +19 -0
package/briefs/growth-engineer/skills/analytics-setup/SKILL.md +109 -0
package/briefs/growth-engineer/skills/brainstorming/SKILL.md +55 -0
package/briefs/growth-engineer/skills/content-strategy/SKILL.md +93 -0
package/briefs/growth-engineer/skills/seo-audit/SKILL.md +412 -0
package/briefs/growth-engineer/skills/seo-audit/evals/evals.json +136 -0
package/briefs/growth-engineer/skills/seo-audit/references/ai-writing-detection.md +200 -0
package/briefs/nextjs-fullstack/brief.yaml +12 -0
package/briefs/nextjs-fullstack/knowledge/conventions.md +57 -0
package/briefs/nextjs-fullstack/personality.md +19 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/SKILL.md +153 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/async-patterns.md +87 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/bundling.md +180 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/data-patterns.md +297 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/debug-tricks.md +105 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/directives.md +73 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/error-handling.md +227 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/file-conventions.md +140 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/font.md +245 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/functions.md +108 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/hydration-error.md +91 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/image.md +173 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/metadata.md +301 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/parallel-routes.md +287 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/route-handlers.md +146 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/rsc-boundaries.md +159 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/runtime-selection.md +39 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/scripts.md +141 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/self-hosting.md +371 -0
package/briefs/nextjs-fullstack/skills/next-best-practices/suspense-boundaries.md +67 -0
package/briefs/nextjs-fullstack/skills/tdd/SKILL.md +53 -0
package/briefs/product-manager/brief.yaml +8 -0
package/briefs/product-manager/knowledge/pm-toolkit.md +51 -0
package/briefs/product-manager/personality.md +19 -0
package/briefs/product-manager/skills/brainstorming/SKILL.md +55 -0
package/briefs/product-manager/skills/specification/SKILL.md +76 -0
package/briefs/qa-engineer/brief.yaml +11 -0
package/briefs/qa-engineer/knowledge/testing-patterns.md +54 -0
package/briefs/qa-engineer/personality.md +24 -0
package/briefs/qa-engineer/skills/qa-test-and-fix/SKILL.md +101 -0
package/briefs/qa-engineer/skills/regression-testing/SKILL.md +95 -0
package/briefs/security-auditor/brief.yaml +12 -0
package/briefs/security-auditor/knowledge/code-patterns.md +49 -0
package/briefs/security-auditor/knowledge/owasp-cheatsheet.md +75 -0
package/briefs/security-auditor/personality.md +23 -0
package/briefs/security-auditor/skills/security-review/SKILL.md +29 -0
package/briefs/security-auditor/skills/systematic-debugging/SKILL.md +46 -0
package/briefs/security-auditor/skills/verification/SKILL.md +47 -0
package/briefs/startup-builder/brief.yaml +8 -0
package/briefs/startup-builder/knowledge/startup-phases.md +64 -0
package/briefs/startup-builder/personality.md +18 -0
package/briefs/startup-builder/skills/ceo-review/SKILL.md +95 -0
package/briefs/startup-builder/skills/launch-strategy/SKILL.md +353 -0
package/briefs/startup-builder/skills/launch-strategy/evals/evals.json +91 -0
package/briefs/startup-builder/skills/tdd/SKILL.md +53 -0
package/briefs/startup-builder/skills/verification/SKILL.md +47 -0
package/briefs/startup-kit/brief.yaml +9 -0
package/briefs/startup-kit/personality.md +18 -0
package/briefs/tech-writer/brief.yaml +8 -0
package/briefs/tech-writer/knowledge/style-guide.md +54 -0
package/briefs/tech-writer/personality.md +19 -0
package/briefs/tech-writer/skills/api-documentation/SKILL.md +390 -0
package/briefs/tech-writer/skills/plan-and-execute/SKILL.md +54 -0
package/briefs/tech-writer/skills/release-notes/SKILL.md +77 -0
package/briefs/typescript-strict/brief.yaml +8 -0
package/briefs/typescript-strict/knowledge/type-patterns.md +117 -0
package/briefs/typescript-strict/personality.md +23 -0
package/briefs/typescript-strict/skills/typescript-advanced-types/SKILL.md +717 -0
package/dist/brief.d.ts +13 -0
package/dist/brief.d.ts.map +1 -0
package/dist/brief.js +90 -0
package/dist/brief.js.map +1 -0
package/dist/cli.d.ts +3 -0
package/dist/cli.d.ts.map +1 -0
package/dist/cli.js +180 -0
package/dist/cli.js.map +1 -0
package/dist/compiler.d.ts +25 -0
package/dist/compiler.d.ts.map +1 -0
package/dist/compiler.js +253 -0
package/dist/compiler.js.map +1 -0
package/dist/index.d.ts +54 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +255 -0
package/dist/index.js.map +1 -0
package/dist/injector.d.ts +17 -0
package/dist/injector.d.ts.map +1 -0
package/dist/injector.js +76 -0
package/dist/injector.js.map +1 -0
package/dist/lock.d.ts +8 -0
package/dist/lock.d.ts.map +1 -0
package/dist/lock.js +50 -0
package/dist/lock.js.map +1 -0
package/dist/resolver.d.ts +24 -0
package/dist/resolver.d.ts.map +1 -0
package/dist/resolver.js +135 -0
package/dist/resolver.js.map +1 -0
package/dist/types.d.ts +61 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +15 -0
package/dist/types.js.map +1 -0
package/package.json +64 -0
package/registry.yaml +91 -0
package/templates/default/brief.yaml +7 -0
package/templates/default/knowledge/.gitkeep +0 -0
package/templates/default/personality.md +12 -0
package/templates/security/brief.yaml +6 -0
package/templates/security/knowledge/.gitkeep +0 -0
package/templates/security/personality.md +20 -0

package/briefs/nextjs-fullstack/skills/next-best-practices/scripts.md ADDED Viewed

@@ -0,0 +1,141 @@
+# Scripts
+Loading third-party scripts in Next.js.
+## Use next/script
+Always use `next/script` instead of native `<script>` tags for better performance.
+```tsx
+// Bad: Native script tag
+<script src="https://example.com/script.js"></script>
+// Good: Next.js Script component
+import Script from 'next/script'
+<Script src="https://example.com/script.js" />
+```
+## Inline Scripts Need ID
+Inline scripts require an `id` attribute for Next.js to track them.
+```tsx
+// Bad: Missing id
+<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+// Good: Has id
+<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+// Good: Inline with id
+<Script id="show-banner">
+  {`document.getElementById('banner').classList.remove('hidden')`}
+</Script>
+```
+## Don't Put Script in Head
+`next/script` should not be placed inside `next/head`. It handles its own positioning.
+```tsx
+// Bad: Script inside Head
+import Head from 'next/head'
+import Script from 'next/script'
+<Head>
+  <Script src="/analytics.js" />
+</Head>
+// Good: Script outside Head
+<Head>
+  <title>Page</title>
+</Head>
+<Script src="/analytics.js" />
+```
+## Loading Strategies
+```tsx
+// afterInteractive (default) - Load after page is interactive
+<Script src="/analytics.js" strategy="afterInteractive" />
+// lazyOnload - Load during idle time
+<Script src="/widget.js" strategy="lazyOnload" />
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+<Script src="/critical.js" strategy="beforeInteractive" />
+// worker - Load in web worker (experimental)
+<Script src="/heavy.js" strategy="worker" />
+```
+## Google Analytics
+Use `@next/third-parties` instead of inline GA scripts.
+```tsx
+// Bad: Inline GA script
+<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
+<Script id="ga-init">
+  {`window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXX');`}
+</Script>
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+      <GoogleAnalytics gaId="G-XXXXX" />
+    </html>
+  )
+}
+```
+## Google Tag Manager
+```tsx
+import { GoogleTagManager } from '@next/third-parties/google'
+export default function Layout({ children }) {
+  return (
+    <html>
+      <GoogleTagManager gtmId="GTM-XXXXX" />
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+## Other Third-Party Scripts
+```tsx
+// YouTube embed
+import { YouTubeEmbed } from '@next/third-parties/google'
+<YouTubeEmbed videoid="dQw4w9WgXcQ" />
+// Google Maps
+import { GoogleMapsEmbed } from '@next/third-parties/google'
+<GoogleMapsEmbed
+  apiKey="YOUR_API_KEY"
+  mode="place"
+  q="Brooklyn+Bridge,New+York,NY"
+/>
+```
+## Quick Reference
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| `<script src="...">` | No optimization | Use `next/script` |
+| `<Script>` without id | Can't track inline scripts | Add `id` attribute |
+| `<Script>` inside `<Head>` | Wrong placement | Move outside Head |
+| Inline GA/GTM scripts | No optimization | Use `@next/third-parties` |
+| `strategy="beforeInteractive"` outside layout | Won't work | Only use in root layout |

package/briefs/nextjs-fullstack/skills/next-best-practices/self-hosting.md ADDED Viewed

@@ -0,0 +1,371 @@
+# Self-Hosting Next.js
+Deploy Next.js outside of Vercel with confidence.
+## Quick Start: Standalone Output
+For Docker or any containerized deployment, use standalone output:
+```js
+// next.config.js
+module.exports = {
+  output: 'standalone',
+};
+```
+This creates a minimal `standalone` folder with only production dependencies:
+```
+.next/
+├── standalone/
+│   ├── server.js          # Entry point
+│   ├── node_modules/      # Only production deps
+│   └── .next/             # Build output
+└── static/                # Must be copied separately
+```
+## Docker Deployment
+### Dockerfile
+```dockerfile
+FROM node:20-alpine AS base
+# Install dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+# Build
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+# Production
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+# Copy standalone output
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+USER nextjs
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+CMD ["node", "server.js"]
+```
+### Docker Compose
+```yaml
+version: '3.8'
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+## PM2 Deployment
+For traditional server deployments:
+```js
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'nextjs',
+    script: '.next/standalone/server.js',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env: {
+      NODE_ENV: 'production',
+      PORT: 3000,
+    },
+  }],
+};
+```
+```bash
+npm run build
+pm2 start ecosystem.config.js
+```
+## ISR and Cache Handlers
+### The Problem
+ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
+- Instance A regenerates page → saves to its local disk
+- Instance B serves stale page → doesn't see Instance A's cache
+- Load balancer sends users to random instances → inconsistent content
+### Solution: Custom Cache Handler
+Next.js 14+ supports custom cache handlers for shared storage:
+```js
+// next.config.js
+module.exports = {
+  cacheHandler: require.resolve('./cache-handler.js'),
+  cacheMaxMemorySize: 0, // Disable in-memory cache
+};
+```
+#### Redis Cache Handler Example
+```js
+// cache-handler.js
+const Redis = require('ioredis');
+const redis = new Redis(process.env.REDIS_URL);
+const CACHE_PREFIX = 'nextjs:';
+module.exports = class CacheHandler {
+  constructor(options) {
+    this.options = options;
+  }
+  async get(key) {
+    const data = await redis.get(CACHE_PREFIX + key);
+    if (!data) return null;
+    const parsed = JSON.parse(data);
+    return {
+      value: parsed.value,
+      lastModified: parsed.lastModified,
+    };
+  }
+  async set(key, data, ctx) {
+    const cacheData = {
+      value: data,
+      lastModified: Date.now(),
+    };
+    // Set TTL based on revalidate option
+    if (ctx?.revalidate) {
+      await redis.setex(
+        CACHE_PREFIX + key,
+        ctx.revalidate,
+        JSON.stringify(cacheData)
+      );
+    } else {
+      await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
+    }
+  }
+  async revalidateTag(tags) {
+    // Implement tag-based invalidation
+    // This requires tracking which keys have which tags
+  }
+};
+```
+#### S3 Cache Handler Example
+```js
+// cache-handler.js
+const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3');
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+const BUCKET = process.env.CACHE_BUCKET;
+module.exports = class CacheHandler {
+  async get(key) {
+    try {
+      const response = await s3.send(new GetObjectCommand({
+        Bucket: BUCKET,
+        Key: `cache/${key}`,
+      }));
+      const body = await response.Body.transformToString();
+      return JSON.parse(body);
+    } catch (err) {
+      if (err.name === 'NoSuchKey') return null;
+      throw err;
+    }
+  }
+  async set(key, data, ctx) {
+    await s3.send(new PutObjectCommand({
+      Bucket: BUCKET,
+      Key: `cache/${key}`,
+      Body: JSON.stringify({
+        value: data,
+        lastModified: Date.now(),
+      }),
+      ContentType: 'application/json',
+    }));
+  }
+};
+```
+## What Works vs What Needs Setup
+| Feature | Single Instance | Multi-Instance | Notes |
+|---------|----------------|----------------|-------|
+| SSR | Yes | Yes | No special setup |
+| SSG | Yes | Yes | Built at deploy time |
+| ISR | Yes | Needs cache handler | Filesystem cache breaks |
+| Image Optimization | Yes | Yes | CPU-intensive, consider CDN |
+| Middleware | Yes | Yes | Runs on Node.js |
+| Edge Runtime | Limited | Limited | Some features Node-only |
+| `revalidatePath/Tag` | Yes | Needs cache handler | Must share cache |
+| `next/font` | Yes | Yes | Fonts bundled at build |
+| Draft Mode | Yes | Yes | Cookie-based |
+## Image Optimization
+Next.js Image Optimization works out of the box but is CPU-intensive.
+### Option 1: Built-in (Simple)
+Works automatically, but consider:
+- Set `deviceSizes` and `imageSizes` in config to limit variants
+- Use `minimumCacheTTL` to reduce regeneration
+```js
+// next.config.js
+module.exports = {
+  images: {
+    minimumCacheTTL: 60 * 60 * 24, // 24 hours
+    deviceSizes: [640, 750, 1080, 1920], // Limit sizes
+  },
+};
+```
+### Option 2: External Loader (Recommended for Scale)
+Offload to Cloudinary, Imgix, or similar:
+```js
+// next.config.js
+module.exports = {
+  images: {
+    loader: 'custom',
+    loaderFile: './lib/image-loader.js',
+  },
+};
+```
+```js
+// lib/image-loader.js
+export default function cloudinaryLoader({ src, width, quality }) {
+  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
+  return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
+}
+```
+## Environment Variables
+### Build-time vs Runtime
+```js
+// Available at build time only (baked into bundle)
+NEXT_PUBLIC_API_URL=https://api.example.com
+// Available at runtime (server-side only)
+DATABASE_URL=postgresql://...
+API_SECRET=...
+```
+### Runtime Configuration
+For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
+```tsx
+// app/api/config/route.ts
+export async function GET() {
+  return Response.json({
+    apiUrl: process.env.API_URL,
+    features: process.env.FEATURES?.split(','),
+  });
+}
+```
+## OpenNext: Serverless Without Vercel
+[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
+```bash
+npx create-sst@latest
+# or
+npx @opennextjs/aws build
+```
+Supports:
+- AWS Lambda + CloudFront
+- Cloudflare Workers
+- Netlify Functions
+- Deno Deploy
+## Health Check Endpoint
+Always include a health check for load balancers:
+```tsx
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Optional: check database connection
+    // await db.$queryRaw`SELECT 1`;
+    return Response.json({ status: 'healthy' }, { status: 200 });
+  } catch (error) {
+    return Response.json({ status: 'unhealthy' }, { status: 503 });
+  }
+}
+```
+## Pre-Deployment Checklist
+1. **Build locally first**: `npm run build` - catch errors before deploy
+2. **Test standalone output**: `node .next/standalone/server.js`
+3. **Set `output: 'standalone'`** for Docker
+4. **Configure cache handler** for multi-instance ISR
+5. **Set `HOSTNAME="0.0.0.0"`** for containers
+6. **Copy `public/` and `.next/static/`** - not included in standalone
+7. **Add health check endpoint**
+8. **Test ISR revalidation** after deployment
+9. **Monitor memory usage** - Node.js defaults may need tuning
+## Testing Cache Handler
+**Critical**: Test your cache handler on every Next.js upgrade:
+```bash
+# Start multiple instances
+PORT=3001 node .next/standalone/server.js &
+PORT=3002 node .next/standalone/server.js &
+# Trigger ISR revalidation
+curl http://localhost:3001/api/revalidate?path=/posts
+# Verify both instances see the update
+curl http://localhost:3001/posts
+curl http://localhost:3002/posts
+# Should return identical content
+```

package/briefs/nextjs-fullstack/skills/next-best-practices/suspense-boundaries.md ADDED Viewed

@@ -0,0 +1,67 @@
+# Suspense Boundaries
+Client hooks that cause CSR bailout without Suspense boundaries.
+## useSearchParams
+Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.
+```tsx
+// Bad: Entire page becomes CSR
+'use client'
+import { useSearchParams } from 'next/navigation'
+export default function SearchBar() {
+  const searchParams = useSearchParams()
+  return <div>Query: {searchParams.get('q')}</div>
+}
+```
+```tsx
+// Good: Wrap in Suspense
+import { Suspense } from 'react'
+import SearchBar from './search-bar'
+export default function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <SearchBar />
+    </Suspense>
+  )
+}
+```
+## usePathname
+Requires Suspense boundary when route has dynamic parameters.
+```tsx
+// In dynamic route [slug]
+// Bad: No Suspense
+'use client'
+import { usePathname } from 'next/navigation'
+export function Breadcrumb() {
+  const pathname = usePathname()
+  return <nav>{pathname}</nav>
+}
+```
+```tsx
+// Good: Wrap in Suspense
+<Suspense fallback={<BreadcrumbSkeleton />}>
+  <Breadcrumb />
+</Suspense>
+```
+If you use `generateStaticParams`, Suspense is optional.
+## Quick Reference
+| Hook | Suspense Required |
+|------|-------------------|
+| `useSearchParams()` | Yes |
+| `usePathname()` | Yes (dynamic routes) |
+| `useParams()` | No |
+| `useRouter()` | No |

package/briefs/nextjs-fullstack/skills/tdd/SKILL.md ADDED Viewed

@@ -0,0 +1,53 @@
+---
+name: tdd
+description: Red-green-refactor cycle for test-driven development
+---
+> Methodology from [obra/superpowers](https://github.com/obra/superpowers) (MIT)
+# Test-Driven Development (TDD)
+Iron law: **no production code without a preceding failing test.**
+## The RED-GREEN-REFACTOR Cycle
+### RED -- Write a Failing Test
+1. Identify the next smallest behavior to implement.
+2. Write a test that asserts that behavior.
+3. Run the test suite. Confirm the new test **fails** for the right reason.
+4. If it passes already, your test is not testing new behavior -- rewrite it.
+### GREEN -- Make It Pass
+1. Write the **minimum** production code to make the failing test pass.
+2. Do not add extra logic, handle future cases, or optimize.
+3. Run the test suite. All tests must be green.
+4. If other tests broke, fix them before moving on.
+### REFACTOR -- Clean Up
+1. Look at the code you just wrote. Remove duplication, improve naming, simplify.
+2. Run the test suite after every refactor step. Stay green.
+3. Do not add new behavior during refactor -- that requires a new RED step.
+## Practical Rules
+- One assertion per test when possible. Focused tests give clearer failure messages.
+- Name tests by behavior: `should reject expired tokens`, not `test_validate_3`.
+- Keep the cycle short: aim for minutes per iteration, not hours.
+- If you are stuck making a test pass, the step is too big. Write a simpler test first.
+- Commit after each GREEN or REFACTOR step. Small commits are cheap insurance.
+## When to Apply TDD
+- New features: always.
+- Bug fixes: write a test that reproduces the bug first, then fix.
+- Refactoring existing untested code: add characterization tests before changing anything.
+## Anti-patterns to Avoid
+- Writing production code first and tests after (test-last is not TDD).
+- Writing multiple tests before making any of them pass.
+- Skipping the REFACTOR step -- tech debt accrues silently.
+- Over-mocking: if your test has more mocks than assertions, rethink the design.

package/briefs/product-manager/brief.yaml ADDED Viewed

@@ -0,0 +1,8 @@
+name: product-manager
+version: "1.0.0"
+description: "Product management specialist — PRDs, user stories, prioritization, roadmapping"
+personality: personality.md
+knowledge:
+  - knowledge/
+skills:
+  - skills/

package/briefs/product-manager/knowledge/pm-toolkit.md ADDED Viewed

@@ -0,0 +1,51 @@
+# Product Management Toolkit
+## Document Outputs
+### PRD (Product Requirements Document)
+- Problem statement: what user pain are we solving? What is the evidence?
+- User stories with acceptance criteria
+- Success metrics: what metric moves if this works? How much? By when?
+- Out of scope: what we are explicitly NOT building
+- Risks: technical, business, and user adoption risks with mitigation plans
+### User Stories
+- Format: "As a [user type], I want [goal] so that [benefit]"
+- Each story has clear acceptance criteria
+- Stories are small enough to complete in one sprint
+- Include edge cases and error states in acceptance criteria
+### Technical Spec Requests
+- Provide enough context for engineering to estimate and design
+- Do not prescribe the solution -- describe the problem and constraints
+- Include performance requirements, scale expectations, and integration points
+- Reference existing system architecture where relevant
+### Prioritization (RICE Framework)
+- **Reach**: How many users will this impact in a given time period?
+- **Impact**: How much will it move the target metric? (3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal)
+- **Confidence**: How sure are we about reach and impact estimates? (100% = high, 80% = medium, 50% = low)
+- **Effort**: How many person-weeks of work?
+- **Score**: (Reach x Impact x Confidence) / Effort
+### Roadmap Items
+- Theme -> Epic -> Story hierarchy with clear sequencing rationale
+- Time horizons: Now (committed), Next (planned), Later (exploratory)
+- Dependencies and blockers identified
+- Flexibility increases with distance -- further out items are less defined
+## Decision Framework
+1. **Start with the problem** -- what user pain are we solving? What is the evidence?
+2. **Define success** -- what metric moves if this works? How much? By when?
+3. **Scope ruthlessly** -- what is the smallest thing we can ship to test the hypothesis?
+4. **Identify risks** -- technical, business, and user adoption risks. Mitigation plan for each.
+5. **Make trade-offs explicit** -- document what we are choosing NOT to do and why
+## Communication Guidelines
+- Lead with the decision or recommendation, then supporting evidence
+- Use structured formats: bullet points, tables, decision matrices
+- Quantify impact wherever possible with specific numbers
+- Tailor detail level to audience: executives get summary, engineers get specifics
+- Status updates: what shipped, what we learned, what is next

package/briefs/product-manager/personality.md ADDED Viewed

@@ -0,0 +1,19 @@
+## Role
+You are a product manager. You define what to build, why to build it, and how to validate that it works. You think in user problems, not features. You communicate in structured documents that align engineering, design, and business stakeholders.
+## Tone
+- Lead with the conclusion, then the reasoning
+- Use bullet points, not paragraphs
+- Quantify whenever possible -- "reduces onboarding time from 5 min to 2 min" not "improves onboarding"
+- Use visual aids (diagrams, wireframes, user flows) over text descriptions
+## Constraints
+- Never propose a feature without articulating the user problem it solves
+- Never skip success metrics -- every feature needs a measurable outcome
+- Never write a PRD longer than 2 pages for an MVP feature
+- Always include "out of scope" to prevent scope creep
+- Always reference user research, data, or competitive analysis -- not just intuition
+- Always define trade-offs explicitly -- document what you are choosing NOT to do and why