Almanac Seed

A unique capability is the inclusion of an agent-reviewer API, a header-gated interface that allows AI review agents to participate alongside human reviewers. AI agents can read an artifact and its comment threads and write comments back programmatically through dedicated API endpoints. These agent-authored comments are tagged and integrated into the same store and display surface as human comments, enabling automated design critique within the collaborative environment.

Almanac operates as a Next.js 14 application using the App Router, with React 18 and TypeScript. It employs NextAuth v4 for authentication, supporting both Google OAuth for optional SSO and a credentials-based passphrase provider for production login. All mutable state—including comments, replies, reactions, viewers, and project metadata—is persisted in Vercel KV, a Redis-compatible store. For local development without KV, it falls back to an in-memory Map. The application serves HTML artifacts from a local directory or from KV, applies security headers portably via next.config.js or middleware, and includes a full Playwright end-to-end test suite for verification.

Users benefit from a streamlined, contextual review process that keeps all feedback directly attached to the design artifacts, eliminating the need to cross-reference external documents or messages. The tool's optimistic UI updates provide immediate visual feedback for actions like adding comments or reactions, enhancing responsiveness. Teams gain a private, secure review environment that supports both human and automated participants, facilitating thorough and efficient design critique.

Concrete use cases include internal team reviews of HTML prototypes, where designers and developers can collaboratively annotate and discuss iterations. It is ideal for critiquing landing page designs, catalog layouts, or any HTML-based mockup. The tool supports reviewing multiple versions of an artifact, allowing teams to track feedback across iterations. The agent API enables automated design critique workflows, where AI agents can provide initial feedback or analysis on new submissions.

The primary target users are internal teams, particularly those at Plow with @plow.co email addresses, who need to review HTML design explorations. It is also suitable for any team requiring a private, locally-hosted design-review tool. The tool integrates with Google for optional SSO and uses Vercel KV for data storage. The technical stack includes Next.js 14, React, TypeScript, NextAuth, Vercel KV, and Playwright for testing. Deployment involves Vercel, with setup steps for Vercel CLI, project creation, Upstash store connection, and environment variable configuration.

In summary, Almanac provides a specialized, collaborative environment for design review, combining intuitive pin-based commenting with support for both human and AI participants. It addresses the fragmentation of design feedback by anchoring conversations directly to the artifact, streamlining the critique process for teams working with HTML explorations.