Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(blog): add Guides and duplicate-work harness variants (#940)

Gustavo Ye6c083c4cf2fe
diff --git a/AGENTS.md b/AGENTS.md
index 323c195ce..4a8205263 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -113,6 +113,8 @@ Use `export const metadata = { ... }` — NOT YAML `---` frontmatter. The loader
Required fields (see `src/web/blog/src/lib/blog/types.ts`): `slug`, `title`, `date`, `author`, `excerpt`, `readingTime`. Missing any → post is skipped with a warning.
+Same-topic article variants MUST use `tags: ["guides"]` in MDX metadata and belong in the supplementary `/guides` directory, not repeated main-Blog posts. See `src/web/blog/README.md` for placement and publishing rules.
+
### Images
- Path: `src/web/blog/public/blog/<slug>/<name>.<ext>`, referenced from MDX as `/blog/<slug>/<name>.<ext>`.
- Naming: short semantic names (`hero.png`, `timeline.png`, `workflow-1-dev-team-pipeline.svg`). No date prefix. Don't repeat the slug — the parent directory already carries it.
diff --git a/src/web/blog/AGENTS.md b/src/web/blog/AGENTS.md
index 7b19f9743..685fb2035 100644
--- a/src/web/blog/AGENTS.md
+++ b/src/web/blog/AGENTS.md
@@ -11,3 +11,7 @@ This block is written and re-added by `next dev` — verify at `node_modules/nex
## Blog publishing contract
Read [README.md](README.md) before adding or revising articles. It defines required metadata, images, links, editorial review, and the checks enforced by Blog build. Keep the documentation and build checks in sync when changing this contract.
+
+## Guides placement
+
+Same-topic content variants (for example, adapting one collaboration task to a different coding-agent combination) MUST use `tags: ["guides"]` in the exported MDX metadata. They belong in the supplementary `/guides` directory, not repeated entries in the main Blog. A genuinely new main-Blog topic needs an editorial explanation of its distinct reader question. Update an existing article when the answer is the same. See README.md for the publishing contract.
diff --git a/src/web/blog/README.md b/src/web/blog/README.md
index 0e3666e40..bddc4e578 100644
--- a/src/web/blog/README.md
+++ b/src/web/blog/README.md
@@ -27,11 +27,26 @@ Include useful explanations, evidence, and relevant links.
```
- Required metadata: `slug`, `title`, `date`, `author`, `excerpt`, `readingTime`. Slug must match the filename, using lowercase words separated by hyphens. Dates use valid `YYYY-MM-DD`; reading time uses `N min read`.
-- Optional: `seoTitle` (nonempty when supplied), `dateModified`, `image`, `draft`, `agentSummary`. `seoTitle` changes search/social titles, not the visible H1. Set `dateModified` only for a substantive revision, never earlier than `date`.
+- Optional: `tags` (unique lowercase kebab-case strings), `seoTitle` (nonempty when supplied), `dateModified`, `image`, `draft`, `agentSummary`. `seoTitle` changes search/social titles, not the visible H1. Set `dateModified` only for a substantive revision, never earlier than `date`.
- The template owns the single H1. Start body sections at `##`, then use `###` for subsections. Do not add another `# Title`.
- Register every published article once in `src/lib/blog/topics.ts`, with its real topic and reader job. A draft uses `draft: true` and must stay out of public discovery/navigation.
- Use valid article paths and existing heading fragments for internal links. Prefer links that help the reader over a required link count. When publishing, check whether a relevant older article should link to this one.
+## Main Blog or Guides?
+
+**Same-topic content variants must use `tags: ["guides"]`.** For example, applying the same collaboration problem to another coding-agent combination belongs in the supplementary `/guides` directory, not another similar main-Blog post. If the question and answer are unchanged, revise/link the existing article instead of creating a duplicate. Main-Blog additions need a distinct reader question explained during editorial review; the build cannot infer semantic similarity.
+
+```js
+export const metadata = {
+ // Keep the normal required article fields.
+ tags: ["guides"],
+};
+```
+
+Continue registering the article once in `src/lib/blog/topics.ts` for its category. Guides reuses those categories and the existing `/blog/<slug>` article URL, author/date display, images and reading template. Missing tags keeps old articles in the main Blog; other tags alone do not move an article. Do not retag existing posts without an editorial decision.
+
+The tag excludes an article from the main Blog list and RSS, Keep exploring and Next Blog. Never add Guides or its articles to the main Blog footer navigation. Readers find guides through `/guides`, direct/search links and relevant editorial body links. A guide's back/category links return to `/guides`. It remains in the existing discovery manifest and sitemap, with its own original canonical URL; **do not add noindex merely because it is absent from the main list**. Drafts remain private.
+
## Images and sharing
Use normal Markdown image syntax and an existing local `/blog/<slug>/...` URL. Supported source formats are PNG, JPEG, WebP and SVG. Each referenced source must be at most 2 MiB; this ceiling is not a recommended target. Keep whole-article image cost low, especially on mobile. Preserve legibility in screenshots and diagrams.
@@ -52,7 +67,7 @@ pnpm --filter @alook/web build:blog
This includes source validation, image preparation, Next compilation, and rendered article validation before Worker packaging. `build:blog:next` is the internal Next/standalone preparation step used by that command. `validate:blog` alone checks source files; it is not the full publishing gate.
-Build errors include missing/invalid required metadata, invalid optional SEO title, duplicate H1 in Markdown, invalid/missing/oversized source images; then, in rendered articles: missing body/title/description, a missing or extra H1, incorrect canonical, noindex, duplicate heading IDs, conflicting/unparseable BlogPosting JSON-LD, missing local article/fragment/image resources, and inconsistent image or OG dimensions. Generated responsive resources must exist. Drafts must not become prerendered public articles. The published article set must match topics, the built index, RSS and discovery manifest (the manifest supplies the main site sitemap).
+Build errors include missing/invalid required metadata, invalid optional SEO title, duplicate H1 in Markdown, invalid/missing/oversized source images; then, in rendered articles: missing body/title/description, a missing or extra H1, incorrect canonical, noindex, duplicate heading IDs, conflicting/unparseable BlogPosting JSON-LD, missing local article/fragment/image resources, and inconsistent image or OG dimensions. Generated responsive resources must exist. Drafts must not become prerendered public articles. The full published article set must match topics and the discovery manifest (which supplies the main site sitemap). The main index and RSS contain only articles without the `guides` tag; `/guides` contains only articles with that tag. Their two index sets must partition the published articles. Footer navigation and Keep exploring / Next Blog recommendations must not expose Guides.
The existing topic tests compare published MDX and the topic registry in both directions. Run related tests when changing templates or publication behavior; negative fixtures must demonstrate that invalid output actually fails. Keep `image-assets.json` regenerated with any source-image change so a clean checkout can typecheck before its first build.
diff --git a/src/web/blog/custom-worker.test.ts b/src/web/blog/custom-worker.test.ts
index 52b3f1897..6ac6f1b4e 100644
--- a/src/web/blog/custom-worker.test.ts
+++ b/src/web/blog/custom-worker.test.ts
@@ -34,8 +34,8 @@ describe("Blog Worker entrypoint", () => {
worker = new BlogWorker({} as ExecutionContext, { ASSETS: {} as Fetcher });
});
- it("delegates public fetches and finalizes cache headers", async () => {
- const response = await worker.fetch(new Request("https://alook.ai/blog"));
+ it.each(["/blog", "/guides", "/guides/"])("finalizes public document headers for %s", async (path) => {
+ const response = await worker.fetch(new Request(`https://alook.ai${path}`));
expect(await response.text()).toBe("node-open-next");
expect(response.headers.get("Cache-Control")).toBe("public, max-age=0, must-revalidate");
});
diff --git a/src/web/blog/custom-worker.ts b/src/web/blog/custom-worker.ts
index f01304306..2dbe96581 100644
--- a/src/web/blog/custom-worker.ts
+++ b/src/web/blog/custom-worker.ts
@@ -20,7 +20,7 @@ export default class BlogWorker extends WorkerEntrypoint<BlogCloudflareEnv> {
const pathname = new URL(request.url).pathname;
if (pathname === MANIFEST_PATH) return new Response("Not Found", { status: 404 });
const response = await fetchOpenNext(request, this.env, this.ctx);
- const publicDocument = pathname === "/blog" || /^\/blog\/[^/.]+\/?$/.test(pathname);
+ const publicDocument = pathname === "/blog" || /^\/guides\/?$/.test(pathname) || /^\/blog\/[^/.]+\/?$/.test(pathname);
return finalizePublicWorkerResponse(response, publicDocument, request);
}
diff --git a/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp
new file mode 100644
index 000000000..d318332eb
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp differ
diff --git a/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp
new file mode 100644
index 000000000..d900e2cb9
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp differ
diff --git a/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/hero.webp b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/hero.webp
new file mode 100644
index 000000000..31a5d83be
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-codex-duplicating-work/hero.webp differ
diff --git a/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp
new file mode 100644
index 000000000..d318332eb
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp differ
diff --git a/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp
new file mode 100644
index 000000000..d900e2cb9
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp differ
diff --git a/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/hero.webp b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/hero.webp
new file mode 100644
index 000000000..31a5d83be
Binary files /dev/null and b/src/web/blog/public/blog/prevent-claude-code-opencode-duplicating-work/hero.webp differ
diff --git a/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp
new file mode 100644
index 000000000..d318332eb
Binary files /dev/null and b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp differ
diff --git a/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/handoff-five.webp b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/handoff-five.webp
new file mode 100644
index 000000000..d900e2cb9
Binary files /dev/null and b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/handoff-five.webp differ
diff --git a/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/hero.webp b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/hero.webp
new file mode 100644
index 000000000..31a5d83be
Binary files /dev/null and b/src/web/blog/public/blog/prevent-codex-opencode-duplicating-work/hero.webp differ
diff --git a/src/web/blog/scripts/validate-rendered.test.ts b/src/web/blog/scripts/validate-rendered.test.ts
index 85fd4bf65..5ed37f86c 100644
--- a/src/web/blog/scripts/validate-rendered.test.ts
+++ b/src/web/blog/scripts/validate-rendered.test.ts
@@ -71,6 +71,7 @@ describe("Blog build gate", () => {
put(".next/server/app/internal/blog-discovery.body", JSON.stringify({ version: 1, posts: [discoveryPost] }));
put(".next/server/app/blog/feed.xml.body", "<rss><channel><item><link>https://alook.ai/blog/example</link></item></channel></rss>");
put(".next/server/app/blog.html", '<a href="/blog/example">Example</a>');
+ put(".next/server/app/guides.html", "<h1>Guides</h1>");
expect(() => validateBlogBuild(root)).not.toThrow();
put(".next/server/app/blog/example.html", html.replace("<h1>Example</h1>", ""));
expect(() => validateBlogBuild(root)).toThrow("one H1");
@@ -78,6 +79,19 @@ describe("Blog build gate", () => {
put(".next/server/app/blog.html", '<a href="/blog/draft">Draft</a>');
expect(() => validateBlogBuild(root)).toThrow("Blog index differs");
put(".next/server/app/blog.html", '<a href="/blog/example">Example</a>');
+ put("src/content/example.mdx", source({ ...metadata, tags: ["guides"] }));
+ expect(() => validateBlogBuild(root)).toThrow("RSS differs");
+ put(".next/server/app/blog/feed.xml.body", "<rss><channel></channel></rss>");
+ expect(() => validateBlogBuild(root)).toThrow("Blog index differs");
+ put(".next/server/app/blog.html", "<h1>Blog</h1>");
+ expect(() => validateBlogBuild(root)).toThrow("Guides index differs");
+ put(".next/server/app/guides.html", '<a href="/blog/example">Example</a>');
+ expect(() => validateBlogBuild(root)).not.toThrow();
+ put(".next/server/app/blog/example.html", html + '<aside data-blog-recommendations><a href="/blog/example">Guide</a></aside>');
+ expect(() => validateBlogBuild(root)).toThrow("Guides leaked");
+ put(".next/server/app/blog/example.html", html + '<footer><a href="/guides">Guides</a></footer>');
+ expect(() => validateBlogBuild(root)).toThrow("Guides leaked");
+ put(".next/server/app/blog/example.html", html);
put("src/content/draft.mdx", source({ ...metadata, slug: "draft", draft: true }));
expect(() => validateBlogBuild(root)).not.toThrow();
put(".next/server/app/blog/draft.html", html);
diff --git a/src/web/blog/scripts/validate-rendered.ts b/src/web/blog/scripts/validate-rendered.ts
index 4a38cce97..f620c18b6 100644
--- a/src/web/blog/scripts/validate-rendered.ts
+++ b/src/web/blog/scripts/validate-rendered.ts
@@ -3,6 +3,7 @@ import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { createRequire } from "node:module";
const { JSDOM } = createRequire(import.meta.url)("jsdom") as { JSDOM: new (html: string, options?: { contentType: string }) => { window: { document: Document } } };
+import { isGuide } from "../src/lib/blog/guides";
import { blogTopics } from "../src/lib/blog/topics";
import { parseBlogDiscoveryManifest } from "../../src/lib/blog-discovery-manifest";
import { isDraftBlogPost, readBlogMetadata, type BlogMetadata } from "../src/lib/blog/validate-assets";
@@ -84,7 +85,8 @@ export function validateBlogBuild(blogRoot: string): void {
const posts: RenderedPost[] = [];
for (const file of readdirSync(content).filter((file) => file.endsWith(".mdx"))) {
const source = readFileSync(resolve(content, file), "utf8");
- const { metadata } = readBlogMetadata(source, file.slice(0, -4));
+ const { metadata, errors } = readBlogMetadata(source, file.slice(0, -4));
+ if (errors.length) throw new Error(errors.join("\n"));
const builtFile = resolve(output, `${metadata.slug}.html`);
if (isDraftBlogPost(source)) {
if (existsSync(builtFile)) throw new Error(`Draft was prerendered: ${metadata.slug}`);
@@ -93,17 +95,33 @@ export function validateBlogBuild(blogRoot: string): void {
posts.push({ metadata, html: readFileSync(builtFile, "utf8") });
}
const expected = posts.map(({ metadata }) => metadata.slug).sort();
- const samePosts = (label: string, slugs: string[]) => {
- if (JSON.stringify([...slugs].sort()) !== JSON.stringify(expected)) throw new Error(`${label} differs from published articles`);
+ const samePosts = (label: string, slugs: string[], expectedSlugs = expected) => {
+ if (JSON.stringify([...slugs].sort()) !== JSON.stringify([...expectedSlugs].sort())) throw new Error(`${label} differs from published articles`);
};
samePosts("Topics", blogTopics.flatMap((topic) => topic.entries.map((entry) => entry.slug)));
const serverRoot = resolve(blogRoot, ".next/server/app");
const discovery = parseBlogDiscoveryManifest(JSON.parse(readFileSync(resolve(serverRoot, "internal/blog-discovery.body"), "utf8")));
samePosts("Discovery manifest", discovery.posts.map((post) => post.slug));
+ const mainSlugs = posts.filter(({ metadata }) => !isGuide(metadata)).map(({ metadata }) => metadata.slug);
+ const guideSlugs = posts.filter(({ metadata }) => isGuide(metadata)).map(({ metadata }) => metadata.slug);
const feed = new JSDOM(readFileSync(resolve(serverRoot, "blog/feed.xml.body"), "utf8"), { contentType: "application/xml" });
- samePosts("RSS", [...feed.window.document.querySelectorAll("item > link")].map((link) => link.textContent?.split("/blog/")[1] ?? ""));
- const index = new JSDOM(readFileSync(resolve(serverRoot, "blog.html"), "utf8"));
- samePosts("Blog index", [...new Set([...index.window.document.querySelectorAll<HTMLAnchorElement>('a[href^="/blog/"]')].map((link) => link.getAttribute("href")!.slice(6)).filter((slug) => !slug.includes("/") && slug !== "feed.xml"))]);
+ samePosts("RSS", [...feed.window.document.querySelectorAll("item > link")].map((link) => link.textContent?.split("/blog/")[1] ?? ""), mainSlugs);
+ const articleLinks = (html: string) => [...new Set([...new JSDOM(html).window.document.querySelectorAll<HTMLAnchorElement>('a[href^="/blog/"]')]
+ .map((link) => link.getAttribute("href")!.slice(6))
+ .filter((slug) => !slug.includes("/") && slug !== "feed.xml"))];
+ const mainIndex = readFileSync(resolve(serverRoot, "blog.html"), "utf8");
+ const guidesIndex = readFileSync(resolve(serverRoot, "guides.html"), "utf8");
+ samePosts("Blog index", articleLinks(mainIndex), mainSlugs);
+ samePosts("Guides index", articleLinks(guidesIndex), guideSlugs);
+ for (const html of [mainIndex, ...posts.map((post) => post.html)]) {
+ const doc = new JSDOM(html).window.document;
+ for (const link of doc.querySelectorAll<HTMLAnchorElement>('footer a[href], [data-blog-recommendations] a[href]')) {
+ const url = new URL(link.getAttribute("href")!, origin);
+ if (url.origin === origin && (/^\/guides\/?$/.test(url.pathname) || guideSlugs.some((slug) => url.pathname.replace(/\/$/, "") === `/blog/${slug}`))) {
+ throw new Error("Guides leaked into Blog footer or recommendations");
+ }
+ }
+ }
const imageAssets = JSON.parse(readFileSync(resolve(blogRoot, "src/lib/blog/image-assets.json"), "utf8"));
const redirects = JSON.parse(readFileSync(resolve(blogRoot, "src/lib/blog/redirects.json"), "utf8")) as { source: string; destination: string }[];
const errors = validateRenderedPosts(posts, (pathname) => { const file = resolve(blogRoot, "public", `.${pathname}`); return existsSync(file) && statSync(file).isFile(); }, imageAssets, Object.fromEntries(redirects.map(({ source, destination }) => [source, destination])));
diff --git a/src/web/blog/src/app/blog/(index)/page.tsx b/src/web/blog/src/app/blog/(index)/page.tsx
index a5b99947b..1101d1b21 100644
--- a/src/web/blog/src/app/blog/(index)/page.tsx
+++ b/src/web/blog/src/app/blog/(index)/page.tsx
@@ -2,6 +2,7 @@ import { ObservedStaticContent } from "@/lib/observability/regions";
import type { Metadata } from "next";
import Image from "next/image";
import Link from "next/link";
+import { isGuide } from "@blog/lib/blog/guides";
import { getAllPosts } from "@blog/lib/blog/posts";
import { blogTopics } from "@blog/lib/blog/topics";
import { buildBlogIndexModel, formatBlogPostDate } from "./model";
@@ -43,7 +44,7 @@ const collectionJsonLd = {
};
export default async function BlogPage() {
- const posts = await getAllPosts();
+ const posts = (await getAllPosts()).filter((post) => !isGuide(post));
const { featured, recent } = buildBlogIndexModel(posts);
return (
diff --git a/src/web/blog/src/app/blog/[slug]/page.tsx b/src/web/blog/src/app/blog/[slug]/page.tsx
index 1b7e1b198..5e2ea7551 100644
--- a/src/web/blog/src/app/blog/[slug]/page.tsx
+++ b/src/web/blog/src/app/blog/[slug]/page.tsx
@@ -3,6 +3,7 @@ import type { Metadata } from "next";
import { notFound } from "next/navigation";
import Link from "next/link";
import { ArrowLeft, ArrowRight } from "lucide-react";
+import { isGuide } from "@blog/lib/blog/guides";
import { getAllPosts, getPostBySlug } from "@blog/lib/blog/posts";
import { buildBlogPostingJsonLd } from "@blog/lib/blog/json-ld";
import {
@@ -44,6 +45,7 @@ export default async function BlogPostPage({
const post = await getPostBySlug(slug);
if (!post) notFound();
+ const directory = isGuide(post) ? "/guides" : "/blog";
const posts = await getAllPosts();
const topic = getBlogTopicBySlug(slug);
const relatedPosts = getRelatedPosts(slug, posts);
@@ -75,11 +77,11 @@ export default async function BlogPostPage({
)}
<article className="blog-article mx-auto max-w-3xl px-6 py-12 sm:py-16">
<Link
- href="/blog"
+ href={directory}
className="inline-flex items-center gap-2 text-sm text-muted-foreground hover:text-foreground transition-colors mb-8"
>
<ArrowLeft className="size-3.5" />
- All posts
+ {isGuide(post) ? "All guides" : "All posts"}
</Link>
<header className="mb-10">
@@ -88,7 +90,7 @@ export default async function BlogPostPage({
</h1>
{topic && (
<Link
- href={`/blog#${topic.id}`}
+ href={`${directory}#${topic.id}`}
className="mt-4 inline-flex rounded-md bg-muted px-2 py-1 text-sm font-medium text-foreground transition-colors hover:bg-accent"
>
{topic.label}
@@ -102,7 +104,7 @@ export default async function BlogPostPage({
</div>
{topic && (relatedPosts.length > 0 || nextTopicBridge) && (
- <aside className="mt-16 border-t border-border pt-8">
+ <aside data-blog-recommendations className="mt-16 border-t border-border pt-8">
<div className="flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
<div>
<h2 className="font-sans text-2xl font-semibold tracking-tight">
diff --git a/src/web/blog/src/app/blog/feed.xml/route.test.ts b/src/web/blog/src/app/blog/feed.xml/route.test.ts
index dbb0ec5c8..7fa6e2fd7 100644
--- a/src/web/blog/src/app/blog/feed.xml/route.test.ts
+++ b/src/web/blog/src/app/blog/feed.xml/route.test.ts
@@ -18,6 +18,7 @@ describe("GET /blog/feed.xml", () => {
it("returns RSS with blog posts and correct content type", async () => {
vi.mocked(getAllPosts).mockResolvedValue([
+ { slug: "guide", title: "Guide", date: "2026-10-12", author: "Alook", excerpt: "Guide", readingTime: "2 min read", tags: ["guides"] },
{
slug: "why-we-built-alook",
title: "Why We Built Alook",
@@ -35,5 +36,6 @@ describe("GET /blog/feed.xml", () => {
expect(body).toContain("<title>Alook Blog</title>");
expect(body).toContain("https://alook.ai/blog/why-we-built-alook");
expect(body).toContain("Why We Built Alook");
+ expect(body).not.toContain("https://alook.ai/blog/guide");
});
});
diff --git a/src/web/blog/src/app/blog/feed.xml/route.ts b/src/web/blog/src/app/blog/feed.xml/route.ts
index 60f63301f..ac6c900de 100644
--- a/src/web/blog/src/app/blog/feed.xml/route.ts
+++ b/src/web/blog/src/app/blog/feed.xml/route.ts
@@ -1,9 +1,10 @@
+import { isGuide } from "@blog/lib/blog/guides";
import { getAllPosts } from "@blog/lib/blog/posts";
export const dynamic = "force-static";
export async function GET() {
- const posts = await getAllPosts();
+ const posts = (await getAllPosts()).filter((post) => !isGuide(post));
const siteUrl = "https://alook.ai";
const items = posts
diff --git a/src/web/blog/src/app/guides/layout.dom.test.tsx b/src/web/blog/src/app/guides/layout.dom.test.tsx
new file mode 100644
index 000000000..cf79a0c21
--- /dev/null
+++ b/src/web/blog/src/app/guides/layout.dom.test.tsx
@@ -0,0 +1,40 @@
+import type { ComponentProps } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, within } from "@/test/react-dom-harness";
+import GuidesLayout from "./layout";
+
+vi.mock("next/link", () => ({
+ default: ({ href, children, ...props }: ComponentProps<"a">) => (
+ <a data-next-link="true" href={href} {...props}>{children}</a>
+ ),
+}));
+vi.mock("next/image", () => ({
+ default: ({ src, alt }: { src: string; alt: string }) => <img src={src} alt={alt} />,
+}));
+
+describe("Guides layout", () => {
+ it("renders its breadcrumb and children with navigation across the correct zone boundaries", () => {
+ render(<GuidesLayout><h1>Guide directory</h1></GuidesLayout>);
+
+ expect(within(screen.getByRole("main")).getByRole("heading", { name: "Guide directory" })).toBeVisible();
+ const breadcrumb = screen.getByRole("link", { name: "Guides", exact: true });
+ expect(breadcrumb).toHaveAttribute("href", "/guides");
+ expect(breadcrumb).toHaveAttribute("data-next-link", "true");
+ expect(screen.getByRole("button", { name: "Toggle theme" })).toBeVisible();
+ for (const home of screen.getAllByRole("link", { name: /^Alook(?: Alook)?$/ })) {
+ expect(home).toHaveAttribute("href", "/");
+ expect(home).not.toHaveAttribute("data-next-link");
+ }
+
+ const footer = within(screen.getByRole("contentinfo"));
+ const navigation = within(footer.getByRole("navigation", { name: "Footer navigation" }));
+ expect(navigation.getAllByRole("link").map((link) => link.getAttribute("href")))
+ .toEqual(["/templates", "/blog", "/llms.txt", "/privacy"]);
+ expect(navigation.getByRole("link", { name: "Blog", exact: true })).toHaveAttribute("data-next-link", "true");
+ for (const name of ["Templates", "llms.txt", "Privacy"]) {
+ expect(navigation.getByRole("link", { name, exact: true })).not.toHaveAttribute("data-next-link");
+ }
+ expect(footer.queryByRole("link", { name: "Guides", exact: true })).not.toBeInTheDocument();
+ expect(footer.getAllByRole("link").some((link) => link.getAttribute("href")?.startsWith("/guides"))).toBe(false);
+ });
+});
diff --git a/src/web/blog/src/app/guides/layout.tsx b/src/web/blog/src/app/guides/layout.tsx
new file mode 100644
index 000000000..2db879e72
--- /dev/null
+++ b/src/web/blog/src/app/guides/layout.tsx
@@ -0,0 +1,7 @@
+import { PublicLayout } from "@/components/public-layout";
+import { ThemeToggle } from "@/components/theme-toggle";
+import { BlogFooter } from "../blog/blog-footer";
+
+export default function GuidesLayout({ children }: { children: React.ReactNode }) {
+ return <PublicLayout zone="blog" breadcrumb="Guides" rightSlot={<ThemeToggle />} footer={<BlogFooter />}>{children}</PublicLayout>;
+}
diff --git a/src/web/blog/src/app/guides/page.dom.test.tsx b/src/web/blog/src/app/guides/page.dom.test.tsx
new file mode 100644
index 000000000..6ac505cc8
--- /dev/null
+++ b/src/web/blog/src/app/guides/page.dom.test.tsx
@@ -0,0 +1,52 @@
+import { createElement, type PropsWithChildren } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, setupUser } from "@/test/react-dom-harness";
+import { getAllPosts } from "@blog/lib/blog/posts";
+import GuidesPage from "./page";
+import BlogPage from "../blog/(index)/page";
+
+vi.mock("@blog/lib/blog/posts", () => ({ getAllPosts: vi.fn() }));
+vi.mock("@/lib/observability/regions", () => ({ ObservedStaticContent: () => null }));
+vi.mock("@/hooks/use-mobile", () => ({ useBreakpoint: () => "desktop" }));
+vi.mock("@/hooks/use-hover-capable", () => ({ useHoverCapable: () => true }));
+vi.mock("next/image", () => ({ default: ({ fill: _fill, preload: _preload, ...props }: Record<string, unknown>) => createElement("img", props) }));
+vi.mock("next/link", () => ({ default: ({ children, ...props }: PropsWithChildren<Record<string, unknown>>) => createElement("a", props, children) }));
+
+const common = { date: "2026-10-12", author: "Alook", excerpt: "A practical example", readingTime: "3 min read" };
+const posts = [
+ { ...common, slug: "claude-code-and-codex-same-team", title: "Coding guide", tags: ["guides"] },
+ { ...common, slug: "ai-agent-team", title: "Team guide", tags: ["guides"] },
+ { ...common, slug: "why-we-built-alook", title: "Main article" },
+];
+
+beforeEach(() => {
+ window.history.replaceState(null, "", "/guides");
+ vi.mocked(getAllPosts).mockResolvedValue(posts);
+});
+
+describe("Guides directory", () => {
+ it("shows every guide including the newest, supports category navigation, and omits empty categories", async () => {
+ render(await GuidesPage());
+ expect(screen.getByRole("heading", { level: 1, name: "Guides" })).toBeVisible();
+ expect(screen.getByRole("link", { name: /Coding guide/ })).toHaveAttribute("href", "/blog/claude-code-and-codex-same-team");
+ expect(screen.getByRole("link", { name: /Team guide/ })).toBeVisible();
+ expect(screen.queryByText("Main article")).not.toBeInTheDocument();
+ expect(screen.queryByRole("button", { name: "Solo business & no-code operations" })).not.toBeInTheDocument();
+ await setupUser().click(screen.getByRole("button", { name: "Coding agents across runtimes & repos" }));
+ expect(screen.getByRole("link", { name: /Coding guide/ })).toBeVisible();
+ expect(screen.queryByRole("link", { name: /Team guide/ })).not.toBeInTheDocument();
+ expect(window.location.hash).toBe("#coding-agents");
+ });
+ it("keeps guides out of the main Blog, including its featured article", async () => {
+ render(await BlogPage());
+ expect(screen.getByRole("link", { name: /Main article/ })).toBeVisible();
+ expect(screen.queryByText("Coding guide")).not.toBeInTheDocument();
+ expect(screen.queryByText("Team guide")).not.toBeInTheDocument();
+ });
+ it("renders the empty directory without inventing articles", async () => {
+ vi.mocked(getAllPosts).mockResolvedValue([posts[2]]);
+ render(await GuidesPage());
+ expect(screen.getByRole("heading", { name: "Guides", level: 1 })).toBeVisible();
+ expect(screen.queryByRole("link")).not.toBeInTheDocument();
+ });
+});
diff --git a/src/web/blog/src/app/guides/page.tsx b/src/web/blog/src/app/guides/page.tsx
new file mode 100644
index 000000000..27e358745
--- /dev/null
+++ b/src/web/blog/src/app/guides/page.tsx
@@ -0,0 +1,33 @@
+import { ObservedStaticContent } from "@/lib/observability/regions";
+import type { Metadata } from "next";
+import { getAllPosts } from "@blog/lib/blog/posts";
+import { isGuide } from "@blog/lib/blog/guides";
+import { blogTopics } from "@blog/lib/blog/topics";
+import { buildBlogIndexModel } from "../blog/(index)/model";
+import { RecentPosts } from "../blog/(index)/recent-posts";
+
+export const metadata: Metadata = {
+ title: "Guides",
+ description: "Practical guides for using specific coding agents together.",
+ alternates: { canonical: "https://alook.ai/guides" },
+ openGraph: {
+ title: "Guides",
+ description: "Practical guides for using specific coding agents together.",
+ url: "https://alook.ai/guides",
+ },
+};
+
+export default async function GuidesPage() {
+ const posts = (await getAllPosts()).filter(isGuide);
+ const { featured, recent } = buildBlogIndexModel(posts);
+ const articles = featured ? [featured, ...recent] : recent;
+ const topicIds = new Set(articles.map((post) => post.topicId));
+ return (
+ <div className="mx-auto max-w-270 px-4 pb-24 pt-12 sm:px-6 sm:pt-20">
+ <ObservedStaticContent key="/guides" pathname="/guides" />
+ <h1 className="font-sans text-3xl font-semibold tracking-tight sm:text-[2.5rem]">Guides</h1>
+ <p className="mt-4 max-w-2xl text-muted-foreground">Practical guides for using specific coding agents together.</p>
+ <RecentPosts posts={articles} topics={blogTopics.filter((topic) => topicIds.has(topic.id))} />
+ </div>
+ );
+}
diff --git a/src/web/blog/src/content/prevent-claude-code-codex-duplicating-work.mdx b/src/web/blog/src/content/prevent-claude-code-codex-duplicating-work.mdx
new file mode 100644
index 000000000..49b960f32
--- /dev/null
+++ b/src/web/blog/src/content/prevent-claude-code-codex-duplicating-work.mdx
@@ -0,0 +1,127 @@
+export const metadata = {
+ slug: "prevent-claude-code-codex-duplicating-work",
+ title: "How to Prevent Claude Code and Codex From Duplicating Work",
+ seoTitle: "Claude Code and Codex: Prevent Duplicate Work",
+ date: "2026-10-12",
+ author: "Alook Team",
+ excerpt: "Stop Claude Code and Codex from repeating the same tasks. Share ownership, finished work and rejected decisions, then connect both harnesses in Alook.",
+ readingTime: "8 min read",
+ image: "/blog/prevent-claude-code-codex-duplicating-work/hero.webp",
+ tags: [
+ "guides"
+ ]
+};
+
+Claude Code finishes a competitive pricing table on Monday. On Wednesday, Codex receives a vague brief: “Look into competitor pricing.” It produces a near-identical table from scratch. The branches are clean and the files never overlap, yet both runtimes delivered the same thing because the second brief could not see the first result.
+
+**To prevent Claude Code and Codex from duplicating work, give every active goal one visible owner, keep its status readable, link finished and rejected artifacts in new briefs, and search existing goals before inventing.** Git can flag line conflicts. It cannot tell an agent that someone already owns the outcome.
+
+This guide applies [the four kinds of task-level duplication](/blog/prevent-coding-agents-duplicating-work) to Claude Code and Codex. Either harness can own the work or receive the handoff; the names below identify responsibilities, not a capability ranking. When two agents collide inside the same files, [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository) covers that layer. Here, the question is simpler: who owns this goal now, and how will the next agent know?
+
+![Two AI agents building the same pricing table because the goal was never claimed, contrasted with one claimed owner and a clear done status](/blog/prevent-claude-code-codex-duplicating-work/hero.webp)
+
+## Give Claude Code and Codex one owner per goal
+
+You assign “implement rate limiting” to Claude Code. Another brief asks Codex to “handle API abuse.” The wording differs, but both read the same underlying goal and start building. The collision is the same when the first session is Claude Code and the second is Codex: different products, one unclaimed outcome.
+
+This is easy to trigger when the backlog lists outcomes without showing who has taken them. Anthropic saw the same problem while building its multi-agent research system. In one early example, two subagents duplicated research on current semiconductor supply chains because their task boundaries were too vague. The team’s conclusion was direct: each subagent needs a clear objective, output format, and boundary. ([Anthropic, 2025](https://www.anthropic.com/engineering/multi-agent-research-system))
+
+**Give each goal one owner before the first tool call.** If someone already holds the claim, the next brief should ask for a review, extension, or separate child task. It should not quietly assign the same build again.
+
+The mechanism can stay simple. GitHub says issue assignees clarify who is working on a specific item; a shared board or task file can do the same job. ([GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users)) Use an agent name, runtime, session ID, or human assignee. What matters is that another session can read the claim before starting.
+
+## Point Codex to work Claude Code has already finished
+
+The pricing table exists, but a later brief still says “research competitor pricing.” With no link to Claude Code’s earlier artifact, Codex has little reason to look for it. It starts over.
+
+**Done work that cannot be found behaves like unfinished work.** Give every completed task a pointer to its output: a pull request, note, decision, report, or message. Then write the next brief as a delta from that artifact:
+
+> Start from Monday’s pricing comparison. Add the new annual plan and verify the enterprise limits. Do not rebuild the table.
+
+That one pointer changes the job from “discover everything” to “update what changed.” If the earlier result is stale, say which part is stale. [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions) explains where these pointers can live when a chat closes or gets compacted.
+
+## Keep rejected approaches visible to Claude Code and Codex
+
+A team reviews a write-through cache and rejects it because concurrent writes make the design unsafe. Later, Codex receives “add caching” without the decision Claude Code helped record and rebuilds the same approach. Its implementation may be competent. It is still work the team already decided not to ship.
+
+Approved work leaves code behind. Rejected work often leaves only a chat message, so it disappears sooner.
+
+**Record a rejection beside the goal, with the reason.** A useful note is short:
+
+> Rejected: write-through cache. Reason: concurrent writes can overwrite newer values. Revisit only if the write model changes.
+
+Link that note from any later brief touching the same decision. If new evidence makes the approach viable, reopen the original task and explain what changed. A fresh ticket with softer wording hides the history. For broader team rules that should apply to every job, see [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track).
+
+## Search existing tasks before either harness starts
+
+Claude Code creates a “billing summary” helper. Codex builds an “invoice rollup” for the same screen. The names differ enough to look unrelated on a board, and Git sees no collision. During review, you discover that both solve the same problem.
+
+**Search open, claimed, done, and rejected goals for the intended outcome.** Look past the ticket title. “Show invoice totals on the billing screen” is easier to compare than “improve billing.” Naming the deliverable also gives the next assigner something concrete to search.
+
+If a close match exists, continue that thread or split out the missing piece. If none exists, claim the goal and start. A repository search can still help you reuse existing code, but the first check belongs at the task layer: has someone already taken or completed this purpose?
+
+![Four ways coding agents duplicate work: two claims on one goal, restarting finished work, reopening rejected approaches, and inventing the same purpose twice](/blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp)
+
+## Use a Claude Code–Codex handoff that prevents redo
+
+![Hand-drawn checklist of five handoff fields that stop coding agents from redoing finished or rejected work](/blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp)
+
+A handoff does not need a transcript. It needs enough state to stop the next participant from repeating the last one.
+
+1. **Goal and definition of done:** What outcome counts as finished?
+2. **Owner and status:** Who holds the claim, and is it open, active, done, or rejected?
+3. **Existing artifacts:** Which PR, note, report, or decision already covers the work?
+4. **Do-not-redo notes:** Which approaches were closed, and why?
+5. **Remaining gap:** What still requires new work?
+
+The fifth field is where the next brief begins. Without it, an agent may treat the whole topic as open again. [How agents keep decisions outside one chat](/blog/shared-context-between-agents) covers fuller handoffs; this compact version has one job: preserve ownership and prior decisions.
+
+Before sending the next task to Claude Code or Codex, ask one plain question: **What will it produce that does not already exist?** If the answer is fuzzy, the task probably needs another pass.
+
+## When visible assignment replaces manual sync
+
+These rules work in an issue tracker, a task file, or a project board. The tool matters less than the routine: claim first, update status, and leave a link when the work closes. The weak point is usually manual upkeep. Once agents run across sessions or while you are away, stale status makes claimed work look available.
+
+Alook gives Claude Code and Codex a shared room where ownership and status stay visible in persistent messages, threads, and marks. You can self-host from [GitHub](https://github.com/alookai/alook), or register at [alook.ai](https://alook.ai) and connect a runtime that stays on your machine. Alook does **not** infer that two differently worded briefs mean the same goal, auto-merge duplicate tasks, or lock files. Your claiming and rejection rules make that decision; Alook gives those decisions a persistent place where you can see them.
+
+Duplicate work often begins before an agent writes code. Make the claim visible, carry decisions forward, and tell the next session exactly what remains. Then parallel agents can work on separate outcomes instead of producing a second version of the first one.
+
+## Claude Code and Codex FAQ
+
+**Why do Claude Code and Codex duplicate work?**
+Claude Code and Codex duplicate work when separate briefs describe the same outcome and no shared record shows that the goal is claimed, done, or rejected. Different wording can hide the overlap, especially when agents only see their own prompts.
+
+**Is duplicate work between Claude Code and Codex a Git problem?**
+Usually no. Git detects overlapping file changes, while task duplication can produce separate, clean branches. Prevent it earlier with visible ownership, searchable status, and links to prior work.
+
+**What should a Claude Code–Codex handoff include?**
+Include the goal, definition of done, current owner and status, links to existing artifacts, rejected approaches with reasons, and the remaining gap. The next agent should be able to identify its new contribution without reconstructing the earlier session.
+
+**Does Alook automatically detect duplicate work?**
+No. Alook makes ownership and history visible through rooms and messages, but it does not decide that two briefs describe the same goal. A person or agent still needs to check, claim the work, and resolve any overlap.
+
+Related:
+
+- [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository)
+- [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track)
+- [How Shared Context Between Agents Actually Works](/blog/shared-context-between-agents)
+- [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions)
+
+## Create the Claude Code and Codex bots in Alook
+
+These steps use Alook in a browser after sign-in. Finish any first-run setup before adding this pair.
+
+1. From a server chat, click the **Home** button with the Alook logo at the top-left. In the left sidebar, open **My Bots**.
+2. If you have no connected machine, click **Connect a machine**. Copy the displayed command and run it in a terminal on the computer that will run the bots. That computer needs Node.js with npm. Wait for **Connected**, then return to **My Bots**. Keep the connection command private.
+3. Click **Create a bot**. Enter the first name below and its description. Under **Machine**, choose the online computer with that runtime installed and authenticated.
+4. Under **Runtime**, select the exact value listed below. If you see a compact **Ready on** summary, click **Change** to show the machine and runtime choices. Review the **Model** choice; you can retain the runtime’s displayed default or choose an available model.
+5. Click **Create bot**, then repeat **Create a bot** for the second bot. If the button says **Open bot chat**, finish the pending first-run bot step before adding another.
+
+- **Claude Owner:** select **Runtime** `claude`. Description: “Check existing tasks, claim one goal, and post the result with its current status.”
+- **Codex Collaborator:** select **Runtime** `codex`. Description: “Read the existing result and decisions, then work only on the assigned remaining gap.”
+
+Open each bot’s chat and provide its checkout path, role, and first bounded task. Ask it to confirm what it can access before editing. The name and description help you identify the bot; they do not provision a repository or enforce file permissions.
+
+To use a shared conversation, open a server you own, click the person-plus **Invite to server** button beside its name, and click **Copy**. Send that invitation to each of your bots in its direct chat and ask it to join. After both join, use a channel they can access, select their real handles from the mention picker, and post the role assignment and handoff there. Do not paste provider keys into the conversation.
+
+If a runtime shows **unavailable**, fix that runtime on the selected machine before creating the bot. If **Create a bot** is disabled because you reached your bot limit, resolve that limit before adding the second bot.
diff --git a/src/web/blog/src/content/prevent-claude-code-opencode-duplicating-work.mdx b/src/web/blog/src/content/prevent-claude-code-opencode-duplicating-work.mdx
new file mode 100644
index 000000000..e63cf473b
--- /dev/null
+++ b/src/web/blog/src/content/prevent-claude-code-opencode-duplicating-work.mdx
@@ -0,0 +1,127 @@
+export const metadata = {
+ slug: "prevent-claude-code-opencode-duplicating-work",
+ title: "How to Prevent Claude Code and OpenCode From Duplicating Work",
+ seoTitle: "Claude Code and OpenCode: Prevent Duplicate Work",
+ date: "2026-10-12",
+ author: "Alook Team",
+ excerpt: "Stop Claude Code and OpenCode from repeating the same tasks. Share ownership, finished work and rejected decisions, then connect both harnesses in Alook.",
+ readingTime: "8 min read",
+ image: "/blog/prevent-claude-code-opencode-duplicating-work/hero.webp",
+ tags: [
+ "guides"
+ ]
+};
+
+Claude Code finishes a competitive pricing table on Monday. On Wednesday, OpenCode receives a vague brief: “Look into competitor pricing.” It produces a near-identical table from scratch. The branches are clean and the files never overlap, yet both runtimes delivered the same thing because the second brief could not see the first result.
+
+**To prevent Claude Code and OpenCode from duplicating work, give every active goal one visible owner, keep its status readable, link finished and rejected artifacts in new briefs, and search existing goals before inventing.** Git can flag line conflicts. It cannot tell an agent that someone already owns the outcome.
+
+This guide applies [the four kinds of task-level duplication](/blog/prevent-coding-agents-duplicating-work) to Claude Code and OpenCode. Either harness can own the work or receive the handoff; the names below identify responsibilities, not a capability ranking. When two agents collide inside the same files, [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository) covers that layer. Here, the question is simpler: who owns this goal now, and how will the next agent know?
+
+![Two AI agents building the same pricing table because the goal was never claimed, contrasted with one claimed owner and a clear done status](/blog/prevent-claude-code-opencode-duplicating-work/hero.webp)
+
+## Give Claude Code and OpenCode one owner per goal
+
+You assign “implement rate limiting” to Claude Code. Another brief asks OpenCode to “handle API abuse.” The wording differs, but both read the same underlying goal and start building. The collision is the same when the first session is Claude Code and the second is OpenCode: different products, one unclaimed outcome.
+
+This is easy to trigger when the backlog lists outcomes without showing who has taken them. Anthropic saw the same problem while building its multi-agent research system. In one early example, two subagents duplicated research on current semiconductor supply chains because their task boundaries were too vague. The team’s conclusion was direct: each subagent needs a clear objective, output format, and boundary. ([Anthropic, 2025](https://www.anthropic.com/engineering/multi-agent-research-system))
+
+**Give each goal one owner before the first tool call.** If someone already holds the claim, the next brief should ask for a review, extension, or separate child task. It should not quietly assign the same build again.
+
+The mechanism can stay simple. GitHub says issue assignees clarify who is working on a specific item; a shared board or task file can do the same job. ([GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users)) Use an agent name, runtime, session ID, or human assignee. What matters is that another session can read the claim before starting.
+
+## Point OpenCode to work Claude Code has already finished
+
+The pricing table exists, but a later brief still says “research competitor pricing.” With no link to Claude Code’s earlier artifact, OpenCode has little reason to look for it. It starts over.
+
+**Done work that cannot be found behaves like unfinished work.** Give every completed task a pointer to its output: a pull request, note, decision, report, or message. Then write the next brief as a delta from that artifact:
+
+> Start from Monday’s pricing comparison. Add the new annual plan and verify the enterprise limits. Do not rebuild the table.
+
+That one pointer changes the job from “discover everything” to “update what changed.” If the earlier result is stale, say which part is stale. [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions) explains where these pointers can live when a chat closes or gets compacted.
+
+## Keep rejected approaches visible to Claude Code and OpenCode
+
+A team reviews a write-through cache and rejects it because concurrent writes make the design unsafe. Later, OpenCode receives “add caching” without the decision Claude Code helped record and rebuilds the same approach. Its implementation may be competent. It is still work the team already decided not to ship.
+
+Approved work leaves code behind. Rejected work often leaves only a chat message, so it disappears sooner.
+
+**Record a rejection beside the goal, with the reason.** A useful note is short:
+
+> Rejected: write-through cache. Reason: concurrent writes can overwrite newer values. Revisit only if the write model changes.
+
+Link that note from any later brief touching the same decision. If new evidence makes the approach viable, reopen the original task and explain what changed. A fresh ticket with softer wording hides the history. For broader team rules that should apply to every job, see [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track).
+
+## Search existing tasks before either harness starts
+
+Claude Code creates a “billing summary” helper. OpenCode builds an “invoice rollup” for the same screen. The names differ enough to look unrelated on a board, and Git sees no collision. During review, you discover that both solve the same problem.
+
+**Search open, claimed, done, and rejected goals for the intended outcome.** Look past the ticket title. “Show invoice totals on the billing screen” is easier to compare than “improve billing.” Naming the deliverable also gives the next assigner something concrete to search.
+
+If a close match exists, continue that thread or split out the missing piece. If none exists, claim the goal and start. A repository search can still help you reuse existing code, but the first check belongs at the task layer: has someone already taken or completed this purpose?
+
+![Four ways coding agents duplicate work: two claims on one goal, restarting finished work, reopening rejected approaches, and inventing the same purpose twice](/blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp)
+
+## Use a Claude Code–OpenCode handoff that prevents redo
+
+![Hand-drawn checklist of five handoff fields that stop coding agents from redoing finished or rejected work](/blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp)
+
+A handoff does not need a transcript. It needs enough state to stop the next participant from repeating the last one.
+
+1. **Goal and definition of done:** What outcome counts as finished?
+2. **Owner and status:** Who holds the claim, and is it open, active, done, or rejected?
+3. **Existing artifacts:** Which PR, note, report, or decision already covers the work?
+4. **Do-not-redo notes:** Which approaches were closed, and why?
+5. **Remaining gap:** What still requires new work?
+
+The fifth field is where the next brief begins. Without it, an agent may treat the whole topic as open again. [How agents keep decisions outside one chat](/blog/shared-context-between-agents) covers fuller handoffs; this compact version has one job: preserve ownership and prior decisions.
+
+Before sending the next task to Claude Code or OpenCode, ask one plain question: **What will it produce that does not already exist?** If the answer is fuzzy, the task probably needs another pass.
+
+## When visible assignment replaces manual sync
+
+These rules work in an issue tracker, a task file, or a project board. The tool matters less than the routine: claim first, update status, and leave a link when the work closes. The weak point is usually manual upkeep. Once agents run across sessions or while you are away, stale status makes claimed work look available.
+
+Alook gives Claude Code and OpenCode a shared room where ownership and status stay visible in persistent messages, threads, and marks. You can self-host from [GitHub](https://github.com/alookai/alook), or register at [alook.ai](https://alook.ai) and connect a runtime that stays on your machine. Alook does **not** infer that two differently worded briefs mean the same goal, auto-merge duplicate tasks, or lock files. Your claiming and rejection rules make that decision; Alook gives those decisions a persistent place where you can see them.
+
+Duplicate work often begins before an agent writes code. Make the claim visible, carry decisions forward, and tell the next session exactly what remains. Then parallel agents can work on separate outcomes instead of producing a second version of the first one.
+
+## Claude Code and OpenCode FAQ
+
+**Why do Claude Code and OpenCode duplicate work?**
+Claude Code and OpenCode duplicate work when separate briefs describe the same outcome and no shared record shows that the goal is claimed, done, or rejected. Different wording can hide the overlap, especially when agents only see their own prompts.
+
+**Is duplicate work between Claude Code and OpenCode a Git problem?**
+Usually no. Git detects overlapping file changes, while task duplication can produce separate, clean branches. Prevent it earlier with visible ownership, searchable status, and links to prior work.
+
+**What should a Claude Code–OpenCode handoff include?**
+Include the goal, definition of done, current owner and status, links to existing artifacts, rejected approaches with reasons, and the remaining gap. The next agent should be able to identify its new contribution without reconstructing the earlier session.
+
+**Does Alook automatically detect duplicate work?**
+No. Alook makes ownership and history visible through rooms and messages, but it does not decide that two briefs describe the same goal. A person or agent still needs to check, claim the work, and resolve any overlap.
+
+Related:
+
+- [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository)
+- [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track)
+- [How Shared Context Between Agents Actually Works](/blog/shared-context-between-agents)
+- [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions)
+
+## Create the Claude Code and OpenCode bots in Alook
+
+These steps use Alook in a browser after sign-in. Finish any first-run setup before adding this pair.
+
+1. From a server chat, click the **Home** button with the Alook logo at the top-left. In the left sidebar, open **My Bots**.
+2. If you have no connected machine, click **Connect a machine**. Copy the displayed command and run it in a terminal on the computer that will run the bots. That computer needs Node.js with npm. Wait for **Connected**, then return to **My Bots**. Keep the connection command private.
+3. Click **Create a bot**. Enter the first name below and its description. Under **Machine**, choose the online computer with that runtime installed and authenticated.
+4. Under **Runtime**, select the exact value listed below. If you see a compact **Ready on** summary, click **Change** to show the machine and runtime choices. For `opencode`, choose a **Model** available to your configured provider; Alook requires an explicit model before enabling **Create bot**. Changing the machine or runtime resets the model selection.
+5. Click **Create bot**, then repeat **Create a bot** for the second bot. If the button says **Open bot chat**, finish the pending first-run bot step before adding another.
+
+- **Claude Owner:** select **Runtime** `claude`. Description: “Check existing tasks, claim one goal, and post the result with its current status.”
+- **OpenCode Collaborator:** select **Runtime** `opencode`. Description: “Read the existing result and decisions, then work only on the assigned remaining gap.”
+
+Open each bot’s chat and provide its checkout path, role, and first bounded task. Ask it to confirm what it can access before editing. The name and description help you identify the bot; they do not provision a repository or enforce file permissions.
+
+To use a shared conversation, open a server you own, click the person-plus **Invite to server** button beside its name, and click **Copy**. Send that invitation to each of your bots in its direct chat and ask it to join. After both join, use a channel they can access, select their real handles from the mention picker, and post the role assignment and handoff there. Do not paste provider keys into the conversation.
+
+If a runtime shows **unavailable**, fix that runtime on the selected machine before creating the bot. If **Create a bot** is disabled because you reached your bot limit, resolve that limit before adding the second bot.
diff --git a/src/web/blog/src/content/prevent-codex-opencode-duplicating-work.mdx b/src/web/blog/src/content/prevent-codex-opencode-duplicating-work.mdx
new file mode 100644
index 000000000..39b0784f0
--- /dev/null
+++ b/src/web/blog/src/content/prevent-codex-opencode-duplicating-work.mdx
@@ -0,0 +1,127 @@
+export const metadata = {
+ slug: "prevent-codex-opencode-duplicating-work",
+ title: "How to Prevent Codex and OpenCode From Duplicating Work",
+ seoTitle: "Codex and OpenCode: Prevent Duplicate Work",
+ date: "2026-10-12",
+ author: "Alook Team",
+ excerpt: "Stop Codex and OpenCode from repeating the same tasks. Share ownership, finished work and rejected decisions, then connect both harnesses in Alook.",
+ readingTime: "8 min read",
+ image: "/blog/prevent-codex-opencode-duplicating-work/hero.webp",
+ tags: [
+ "guides"
+ ]
+};
+
+Codex finishes a competitive pricing table on Monday. On Wednesday, OpenCode receives a vague brief: “Look into competitor pricing.” It produces a near-identical table from scratch. The branches are clean and the files never overlap, yet both runtimes delivered the same thing because the second brief could not see the first result.
+
+**To prevent Codex and OpenCode from duplicating work, give every active goal one visible owner, keep its status readable, link finished and rejected artifacts in new briefs, and search existing goals before inventing.** Git can flag line conflicts. It cannot tell an agent that someone already owns the outcome.
+
+This guide applies [the four kinds of task-level duplication](/blog/prevent-coding-agents-duplicating-work) to Codex and OpenCode. Either harness can own the work or receive the handoff; the names below identify responsibilities, not a capability ranking. When two agents collide inside the same files, [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository) covers that layer. Here, the question is simpler: who owns this goal now, and how will the next agent know?
+
+![Two AI agents building the same pricing table because the goal was never claimed, contrasted with one claimed owner and a clear done status](/blog/prevent-codex-opencode-duplicating-work/hero.webp)
+
+## Give Codex and OpenCode one owner per goal
+
+You assign “implement rate limiting” to Codex. Another brief asks OpenCode to “handle API abuse.” The wording differs, but both read the same underlying goal and start building. The collision is the same when the first session is Codex and the second is OpenCode: different products, one unclaimed outcome.
+
+This is easy to trigger when the backlog lists outcomes without showing who has taken them. Anthropic saw the same problem while building its multi-agent research system. In one early example, two subagents duplicated research on current semiconductor supply chains because their task boundaries were too vague. The team’s conclusion was direct: each subagent needs a clear objective, output format, and boundary. ([Anthropic, 2025](https://www.anthropic.com/engineering/multi-agent-research-system))
+
+**Give each goal one owner before the first tool call.** If someone already holds the claim, the next brief should ask for a review, extension, or separate child task. It should not quietly assign the same build again.
+
+The mechanism can stay simple. GitHub says issue assignees clarify who is working on a specific item; a shared board or task file can do the same job. ([GitHub Docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users)) Use an agent name, runtime, session ID, or human assignee. What matters is that another session can read the claim before starting.
+
+## Point OpenCode to work Codex has already finished
+
+The pricing table exists, but a later brief still says “research competitor pricing.” With no link to Codex’s earlier artifact, OpenCode has little reason to look for it. It starts over.
+
+**Done work that cannot be found behaves like unfinished work.** Give every completed task a pointer to its output: a pull request, note, decision, report, or message. Then write the next brief as a delta from that artifact:
+
+> Start from Monday’s pricing comparison. Add the new annual plan and verify the enterprise limits. Do not rebuild the table.
+
+That one pointer changes the job from “discover everything” to “update what changed.” If the earlier result is stale, say which part is stale. [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions) explains where these pointers can live when a chat closes or gets compacted.
+
+## Keep rejected approaches visible to Codex and OpenCode
+
+A team reviews a write-through cache and rejects it because concurrent writes make the design unsafe. Later, OpenCode receives “add caching” without the decision Codex helped record and rebuilds the same approach. Its implementation may be competent. It is still work the team already decided not to ship.
+
+Approved work leaves code behind. Rejected work often leaves only a chat message, so it disappears sooner.
+
+**Record a rejection beside the goal, with the reason.** A useful note is short:
+
+> Rejected: write-through cache. Reason: concurrent writes can overwrite newer values. Revisit only if the write model changes.
+
+Link that note from any later brief touching the same decision. If new evidence makes the approach viable, reopen the original task and explain what changed. A fresh ticket with softer wording hides the history. For broader team rules that should apply to every job, see [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track).
+
+## Search existing tasks before either harness starts
+
+Codex creates a “billing summary” helper. OpenCode builds an “invoice rollup” for the same screen. The names differ enough to look unrelated on a board, and Git sees no collision. During review, you discover that both solve the same problem.
+
+**Search open, claimed, done, and rejected goals for the intended outcome.** Look past the ticket title. “Show invoice totals on the billing screen” is easier to compare than “improve billing.” Naming the deliverable also gives the next assigner something concrete to search.
+
+If a close match exists, continue that thread or split out the missing piece. If none exists, claim the goal and start. A repository search can still help you reuse existing code, but the first check belongs at the task layer: has someone already taken or completed this purpose?
+
+![Four ways coding agents duplicate work: two claims on one goal, restarting finished work, reopening rejected approaches, and inventing the same purpose twice](/blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp)
+
+## Use a Codex–OpenCode handoff that prevents redo
+
+![Hand-drawn checklist of five handoff fields that stop coding agents from redoing finished or rejected work](/blog/prevent-codex-opencode-duplicating-work/handoff-five.webp)
+
+A handoff does not need a transcript. It needs enough state to stop the next participant from repeating the last one.
+
+1. **Goal and definition of done:** What outcome counts as finished?
+2. **Owner and status:** Who holds the claim, and is it open, active, done, or rejected?
+3. **Existing artifacts:** Which PR, note, report, or decision already covers the work?
+4. **Do-not-redo notes:** Which approaches were closed, and why?
+5. **Remaining gap:** What still requires new work?
+
+The fifth field is where the next brief begins. Without it, an agent may treat the whole topic as open again. [How agents keep decisions outside one chat](/blog/shared-context-between-agents) covers fuller handoffs; this compact version has one job: preserve ownership and prior decisions.
+
+Before sending the next task to Codex or OpenCode, ask one plain question: **What will it produce that does not already exist?** If the answer is fuzzy, the task probably needs another pass.
+
+## When visible assignment replaces manual sync
+
+These rules work in an issue tracker, a task file, or a project board. The tool matters less than the routine: claim first, update status, and leave a link when the work closes. The weak point is usually manual upkeep. Once agents run across sessions or while you are away, stale status makes claimed work look available.
+
+Alook gives Codex and OpenCode a shared room where ownership and status stay visible in persistent messages, threads, and marks. You can self-host from [GitHub](https://github.com/alookai/alook), or register at [alook.ai](https://alook.ai) and connect a runtime that stays on your machine. Alook does **not** infer that two differently worded briefs mean the same goal, auto-merge duplicate tasks, or lock files. Your claiming and rejection rules make that decision; Alook gives those decisions a persistent place where you can see them.
+
+Duplicate work often begins before an agent writes code. Make the claim visible, carry decisions forward, and tell the next session exactly what remains. Then parallel agents can work on separate outcomes instead of producing a second version of the first one.
+
+## Codex and OpenCode FAQ
+
+**Why do Codex and OpenCode duplicate work?**
+Codex and OpenCode duplicate work when separate briefs describe the same outcome and no shared record shows that the goal is claimed, done, or rejected. Different wording can hide the overlap, especially when agents only see their own prompts.
+
+**Is duplicate work between Codex and OpenCode a Git problem?**
+Usually no. Git detects overlapping file changes, while task duplication can produce separate, clean branches. Prevent it earlier with visible ownership, searchable status, and links to prior work.
+
+**What should a Codex–OpenCode handoff include?**
+Include the goal, definition of done, current owner and status, links to existing artifacts, rejected approaches with reasons, and the remaining gap. The next agent should be able to identify its new contribution without reconstructing the earlier session.
+
+**Does Alook automatically detect duplicate work?**
+No. Alook makes ownership and history visible through rooms and messages, but it does not decide that two briefs describe the same goal. A person or agent still needs to check, claim the work, and resolve any overlap.
+
+Related:
+
+- [What Happens When Multiple AI Agents Edit the Same Repository?](/blog/multiple-ai-agents-edit-same-repository)
+- [How to Run an AI Agent Team That Stays on Track](/blog/run-ai-agent-team-that-stays-on-track)
+- [How Shared Context Between Agents Actually Works](/blog/shared-context-between-agents)
+- [How to Keep Context Across Coding Agent Sessions](/blog/keep-context-across-coding-agent-sessions)
+
+## Create the Codex and OpenCode bots in Alook
+
+These steps use Alook in a browser after sign-in. Finish any first-run setup before adding this pair.
+
+1. From a server chat, click the **Home** button with the Alook logo at the top-left. In the left sidebar, open **My Bots**.
+2. If you have no connected machine, click **Connect a machine**. Copy the displayed command and run it in a terminal on the computer that will run the bots. That computer needs Node.js with npm. Wait for **Connected**, then return to **My Bots**. Keep the connection command private.
+3. Click **Create a bot**. Enter the first name below and its description. Under **Machine**, choose the online computer with that runtime installed and authenticated.
+4. Under **Runtime**, select the exact value listed below. If you see a compact **Ready on** summary, click **Change** to show the machine and runtime choices. For `opencode`, choose a **Model** available to your configured provider; Alook requires an explicit model before enabling **Create bot**. Changing the machine or runtime resets the model selection.
+5. Click **Create bot**, then repeat **Create a bot** for the second bot. If the button says **Open bot chat**, finish the pending first-run bot step before adding another.
+
+- **Codex Owner:** select **Runtime** `codex`. Description: “Check existing tasks, claim one goal, and post the result with its current status.”
+- **OpenCode Collaborator:** select **Runtime** `opencode`. Description: “Read the existing result and decisions, then work only on the assigned remaining gap.”
+
+Open each bot’s chat and provide its checkout path, role, and first bounded task. Ask it to confirm what it can access before editing. The name and description help you identify the bot; they do not provision a repository or enforce file permissions.
+
+To use a shared conversation, open a server you own, click the person-plus **Invite to server** button beside its name, and click **Copy**. Send that invitation to each of your bots in its direct chat and ask it to join. After both join, use a channel they can access, select their real handles from the mention picker, and post the role assignment and handoff there. Do not paste provider keys into the conversation.
+
+If a runtime shows **unavailable**, fix that runtime on the selected machine before creating the bot. If **Create a bot** is disabled because you reached your bot limit, resolve that limit before adding the second bot.
diff --git a/src/web/blog/src/lib/blog/guides.test.ts b/src/web/blog/src/lib/blog/guides.test.ts
new file mode 100644
index 000000000..6bb99523d
--- /dev/null
+++ b/src/web/blog/src/lib/blog/guides.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+import { isGuide, validBlogTags } from "./guides";
+import { readBlogMetadata } from "./validate-assets";
+import { validateMetadata } from "./posts/validate-metadata";
+
+const post = { slug: "example", title: "Example", date: "2026-10-12", author: "Alook", excerpt: "Example", readingTime: "5 min read" };
+
+describe("Guides metadata", () => {
+ it("keeps legacy/other tags in the main Blog and recognizes the explicit tag", () => {
+ expect(isGuide({})).toBe(false);
+ expect(isGuide({ tags: ["coding"] })).toBe(false);
+ expect(isGuide({ tags: ["coding", "guides"] })).toBe(true);
+ expect(validBlogTags(undefined)).toBe(true);
+ expect(validBlogTags([])).toBe(true);
+ });
+ it.each([null, "guides", ["Guides"], [""], [1], ["guides", "guides"]])("rejects invalid runtime tags %j", (tags) => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ expect(validateMetadata({ ...post, tags }, "example.mdx")).toBe(false);
+ warn.mockRestore();
+ });
+ it("reads literal tags including comments, single quotes and trailing commas", () => {
+ const source = `export const metadata = { ${Object.entries(post).map(([k,v]) => `${k}: ${JSON.stringify(v)}`).join(",")}, tags: [/* category */ 'coding', "guides",], };`;
+ const result = readBlogMetadata(source, "example");
+ expect(result.errors).toEqual([]);
+ expect(result.metadata.tags).toEqual(["coding", "guides"]);
+ expect(validateMetadata({ ...post, tags: result.metadata.tags }, "example.mdx")).toBe(true);
+ });
+ it.each(['"guides"', '["guides", "guides"]', '["guides", variable]', 'getTags()', '["Guides"]'])("rejects nonliteral or invalid source tags %s", (value) => {
+ expect(readBlogMetadata(`export const metadata = { tags: ${value} }`, "example").errors.join()).toContain("tags must be");
+ });
+});
diff --git a/src/web/blog/src/lib/blog/guides.ts b/src/web/blog/src/lib/blog/guides.ts
new file mode 100644
index 000000000..b1cee5c55
--- /dev/null
+++ b/src/web/blog/src/lib/blog/guides.ts
@@ -0,0 +1,9 @@
+export function isGuide(post: { tags?: readonly string[] }): boolean {
+ return post.tags?.includes("guides") ?? false;
+}
+
+export function validBlogTags(value: unknown): value is string[] | undefined {
+ return value === undefined || (Array.isArray(value) && value.every(
+ (tag) => typeof tag === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(tag),
+ ) && new Set(value).size === value.length);
+}
diff --git a/src/web/blog/src/lib/blog/image-assets.json b/src/web/blog/src/lib/blog/image-assets.json
index 98783edc6..7589f7334 100644
--- a/src/web/blog/src/lib/blog/image-assets.json
+++ b/src/web/blog/src/lib/blog/image-assets.json
@@ -53,6 +53,15 @@
"/blog/personal-ai-company/comparison.webp": {"width":1200,"height":630,"srcSet":"/blog/_generated/c013b6a1e62aa7d7-480.webp 480w, /blog/_generated/c013b6a1e62aa7d7-960.webp 960w, /blog/personal-ai-company/comparison.webp 1200w"},
"/blog/personal-ai-company/hero.webp": {"width":1200,"height":630,"srcSet":"/blog/_generated/00a72af97ff1a5f3-480.webp 480w, /blog/_generated/00a72af97ff1a5f3-960.webp 960w, /blog/personal-ai-company/hero.webp 1200w"},
"/blog/personal-ai-company/timeline.webp": {"width":1200,"height":630,"srcSet":"/blog/_generated/5408f87223e0696c-480.webp 480w, /blog/_generated/5408f87223e0696c-960.webp 960w, /blog/personal-ai-company/timeline.webp 1200w"},
+ "/blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/7c7b498ba795f73e-480.webp 480w, /blog/_generated/7c7b498ba795f73e-960.webp 960w, /blog/prevent-claude-code-codex-duplicating-work/four-duplicates.webp 1536w"},
+ "/blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/324365e41410efb9-480.webp 480w, /blog/_generated/324365e41410efb9-960.webp 960w, /blog/prevent-claude-code-codex-duplicating-work/handoff-five.webp 1536w"},
+ "/blog/prevent-claude-code-codex-duplicating-work/hero.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/d2a9d2aa0dd8ab63-480.webp 480w, /blog/_generated/d2a9d2aa0dd8ab63-960.webp 960w, /blog/prevent-claude-code-codex-duplicating-work/hero.webp 1536w"},
+ "/blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/7c7b498ba795f73e-480.webp 480w, /blog/_generated/7c7b498ba795f73e-960.webp 960w, /blog/prevent-claude-code-opencode-duplicating-work/four-duplicates.webp 1536w"},
+ "/blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/324365e41410efb9-480.webp 480w, /blog/_generated/324365e41410efb9-960.webp 960w, /blog/prevent-claude-code-opencode-duplicating-work/handoff-five.webp 1536w"},
+ "/blog/prevent-claude-code-opencode-duplicating-work/hero.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/d2a9d2aa0dd8ab63-480.webp 480w, /blog/_generated/d2a9d2aa0dd8ab63-960.webp 960w, /blog/prevent-claude-code-opencode-duplicating-work/hero.webp 1536w"},
+ "/blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/7c7b498ba795f73e-480.webp 480w, /blog/_generated/7c7b498ba795f73e-960.webp 960w, /blog/prevent-codex-opencode-duplicating-work/four-duplicates.webp 1536w"},
+ "/blog/prevent-codex-opencode-duplicating-work/handoff-five.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/324365e41410efb9-480.webp 480w, /blog/_generated/324365e41410efb9-960.webp 960w, /blog/prevent-codex-opencode-duplicating-work/handoff-five.webp 1536w"},
+ "/blog/prevent-codex-opencode-duplicating-work/hero.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/d2a9d2aa0dd8ab63-480.webp 480w, /blog/_generated/d2a9d2aa0dd8ab63-960.webp 960w, /blog/prevent-codex-opencode-duplicating-work/hero.webp 1536w"},
"/blog/prevent-coding-agents-duplicating-work/four-duplicates.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/7c7b498ba795f73e-480.webp 480w, /blog/_generated/7c7b498ba795f73e-960.webp 960w, /blog/prevent-coding-agents-duplicating-work/four-duplicates.webp 1536w"},
"/blog/prevent-coding-agents-duplicating-work/handoff-five.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/324365e41410efb9-480.webp 480w, /blog/_generated/324365e41410efb9-960.webp 960w, /blog/prevent-coding-agents-duplicating-work/handoff-five.webp 1536w"},
"/blog/prevent-coding-agents-duplicating-work/hero.webp": {"width":1536,"height":1024,"srcSet":"/blog/_generated/d2a9d2aa0dd8ab63-480.webp 480w, /blog/_generated/d2a9d2aa0dd8ab63-960.webp 960w, /blog/prevent-coding-agents-duplicating-work/hero.webp 1536w"},
diff --git a/src/web/blog/src/lib/blog/posts/validate-metadata.ts b/src/web/blog/src/lib/blog/posts/validate-metadata.ts
index cbcf5f1cf..06ca76ab0 100644
--- a/src/web/blog/src/lib/blog/posts/validate-metadata.ts
+++ b/src/web/blog/src/lib/blog/posts/validate-metadata.ts
@@ -1,3 +1,4 @@
+import { validBlogTags } from "../guides";
import type { BlogPost } from "../types";
const REQUIRED_FIELDS: (keyof BlogPost)[] = [
@@ -21,5 +22,9 @@ export function validateMetadata(
return false;
}
}
+ if (!validBlogTags(metadata.tags)) {
+ console.warn(`[blog] Skipping ${file}: invalid tags`);
+ return false;
+ }
return true;
}
diff --git a/src/web/blog/src/lib/blog/topics.test.ts b/src/web/blog/src/lib/blog/topics.test.ts
index e57566268..42e5b4ddb 100644
--- a/src/web/blog/src/lib/blog/topics.test.ts
+++ b/src/web/blog/src/lib/blog/topics.test.ts
@@ -47,14 +47,14 @@ describe("blogTopics", () => {
expect(registrySlugs).toEqual(publishedSlugs);
});
- it("covers all 26 published slugs exactly once", () => {
+ it("covers all 29 published slugs exactly once", () => {
const orderedSlugs = blogTopics.map((topic) =>
topic.entries.map((entry) => entry.slug)
);
const slugs = orderedSlugs.flat();
- expect(slugs).toHaveLength(26);
- expect(new Set(slugs).size).toBe(26);
+ expect(slugs).toHaveLength(29);
+ expect(new Set(slugs).size).toBe(29);
expect(orderedSlugs).toEqual([
[
"ai-agent-vs-chatbot",
@@ -72,6 +72,9 @@ describe("blogTopics", () => {
"claude-code-dynamic-workflow-alternative",
"keep-context-across-coding-agent-sessions",
"multiple-ai-agents-edit-same-repository",
+ "prevent-claude-code-codex-duplicating-work",
+ "prevent-codex-opencode-duplicating-work",
+ "prevent-claude-code-opencode-duplicating-work",
"prevent-coding-agents-duplicating-work",
],
[
@@ -109,6 +112,9 @@ describe("blogTopics", () => {
)
)
).toEqual({
+ "prevent-claude-code-codex-duplicating-work": "Prevent Claude Code and Codex from duplicating work",
+ "prevent-codex-opencode-duplicating-work": "Prevent Codex and OpenCode from duplicating work",
+ "prevent-claude-code-opencode-duplicating-work": "Prevent Claude Code and OpenCode from duplicating work",
"ai-agent-vs-chatbot": "Decide whether I need an agent or a chatbot",
"local-ai-agents":
"Choose which parts of an AI agent should run locally",
@@ -228,3 +234,19 @@ describe("topic discovery", () => {
);
});
});
+
+describe("Guides recommendation isolation", () => {
+ it("excludes a tagged pillar and neighboring articles from Keep exploring", () => {
+ const current = blogTopics[1].entries[0].slug;
+ const guides = new Set([blogTopics[1].pillarSlug, blogTopics[1].entries[1].slug]);
+ const posts = allPosts.map((post) => guides.has(post.slug) ? { ...post, tags: ["guides"] } : post);
+ const related = getRelatedPosts(current, posts, 20);
+ expect(related.length).toBeGreaterThan(0);
+ expect(related.every((post) => !guides.has(post.slug))).toBe(true);
+ });
+ it("omits Next Blog when the next pillar is a guide, without refilling from the full registry", () => {
+ const nextPillar = blogTopics[1].pillarSlug;
+ const posts = allPosts.map((post) => post.slug === nextPillar ? { ...post, tags: ["guides"] } : post);
+ expect(getNextTopicBridge(blogTopics[0].pillarSlug, posts)).toBeUndefined();
+ });
+});
diff --git a/src/web/blog/src/lib/blog/topics.ts b/src/web/blog/src/lib/blog/topics.ts
index 8af4729e0..00feb47c6 100644
--- a/src/web/blog/src/lib/blog/topics.ts
+++ b/src/web/blog/src/lib/blog/topics.ts
@@ -1,3 +1,4 @@
+import { isGuide } from "./guides";
import type { BlogPost } from "./types";
export type BlogTopicEntry = {
@@ -58,6 +59,9 @@ export const blogTopics = [
slug: "multiple-ai-agents-edit-same-repository",
userJob: "Run parallel agents on one repo without conflicts",
},
+ { slug: "prevent-claude-code-codex-duplicating-work", userJob: "Prevent Claude Code and Codex from duplicating work" },
+ { slug: "prevent-codex-opencode-duplicating-work", userJob: "Prevent Codex and OpenCode from duplicating work" },
+ { slug: "prevent-claude-code-opencode-duplicating-work", userJob: "Prevent Claude Code and OpenCode from duplicating work" },
{
slug: "prevent-coding-agents-duplicating-work",
userJob: "Stop agents from redoing each other's work",
@@ -151,6 +155,7 @@ export function getRelatedPosts(
posts: readonly BlogPost[],
limit = 3
): BlogPost[] {
+ posts = posts.filter((post) => !isGuide(post));
const topic = getBlogTopicBySlug(slug);
if (!topic || limit <= 0) return [];
@@ -190,6 +195,6 @@ export function getNextTopicBridge(
if (topicIndex === -1) return undefined;
const nextTopic = blogTopics[(topicIndex + 1) % blogTopics.length];
- const pillar = posts.find((post) => post.slug === nextTopic.pillarSlug);
+ const pillar = posts.find((post) => !isGuide(post) && post.slug === nextTopic.pillarSlug);
return pillar ? { topic: nextTopic, post: pillar } : undefined;
}
diff --git a/src/web/blog/src/lib/blog/types.ts b/src/web/blog/src/lib/blog/types.ts
index 17e20c8a2..95586b490 100644
--- a/src/web/blog/src/lib/blog/types.ts
+++ b/src/web/blog/src/lib/blog/types.ts
@@ -1,5 +1,6 @@
export type BlogPost = {
slug: string;
+ tags?: string[];
title: string;
seoTitle?: string;
date: string;
diff --git a/src/web/blog/src/lib/blog/validate-assets.ts b/src/web/blog/src/lib/blog/validate-assets.ts
index 8f3a31fb9..3f7f920c6 100644
--- a/src/web/blog/src/lib/blog/validate-assets.ts
+++ b/src/web/blog/src/lib/blog/validate-assets.ts
@@ -1,5 +1,7 @@
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
import { extname, join } from "path";
+import ts from "typescript";
+import { validBlogTags } from "./guides";
export type BlogAssetError = string;
@@ -29,7 +31,7 @@ const OPTIONAL_METADATA_FIELDS = ["dateModified", "image", "seoTitle"] as const;
const ALLOWED_IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".svg", ".webp"]);
const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
-export type BlogMetadata = Record<string, string>;
+export type BlogMetadata = Record<(typeof REQUIRED_METADATA_FIELDS)[number] | (typeof OPTIONAL_METADATA_FIELDS)[number], string> & { tags?: string[] };
function extractMetadataObject(content: string): string | null {
const declaration = /export\s+const\s+metadata\s*=\s*\{/.exec(content);
@@ -109,18 +111,32 @@ export function readBlogMetadata(
const object = extractMetadataObject(content);
if (!object) {
return {
- metadata: {},
+ metadata: {} as BlogMetadata,
errors: [`[post: ${fileSlug}] Missing or unterminated export const metadata object.`],
};
}
- const metadata: BlogMetadata = {};
+ const metadata = {} as BlogMetadata;
const errors: BlogAssetError[] = [];
for (const field of [...REQUIRED_METADATA_FIELDS, ...OPTIONAL_METADATA_FIELDS]) {
const value = readStringProperty(object, field);
if (value !== null) metadata[field] = value;
}
+ const parsed = ts.createSourceFile("metadata.ts", `const metadata = {${object}}`, ts.ScriptTarget.Latest, true);
+ const declaration = (parsed.statements[0] as ts.VariableStatement).declarationList.declarations[0];
+ const expression = declaration.initializer;
+ if (expression && ts.isObjectLiteralExpression(expression)) {
+ const tags = expression.properties.find((property) => property.name && property.name.getText(parsed).replace(/^['"]|['"]$/g, "") === "tags");
+ if (tags) {
+ const value = ts.isPropertyAssignment(tags) && ts.isArrayLiteralExpression(tags.initializer)
+ ? tags.initializer.elements.map((element) => ts.isStringLiteral(element) ? element.text : null)
+ : null;
+ if (validBlogTags(value)) metadata.tags = value;
+ else errors.push(`[post: ${fileSlug}] tags must be an array of unique lowercase kebab-case strings.`);
+ }
+ }
+
if (/(?:^|[,\n])\s*seoTitle\s*:/.test(object) && !metadata.seoTitle?.trim()) {
errors.push(`[post: ${fileSlug}] Optional seoTitle must be a non-empty string.`);
}
diff --git a/src/web/blog/wrangler.toml b/src/web/blog/wrangler.toml
index 570500b22..80bea3856 100644
--- a/src/web/blog/wrangler.toml
+++ b/src/web/blog/wrangler.toml
@@ -30,6 +30,10 @@ run_worker_first = true
pattern = "alook.ai/blog*"
zone_name = "alook.ai"
+[[routes]]
+pattern = "alook.ai/guides*"
+zone_name = "alook.ai"
+
[[routes]]
pattern = "alook.ai/og/blog*"
zone_name = "alook.ai"
diff --git a/src/web/scripts/dev-zone-ingress.mjs b/src/web/scripts/dev-zone-ingress.mjs
index 5164b35ca..bdaf6292b 100644
--- a/src/web/scripts/dev-zone-ingress.mjs
+++ b/src/web/scripts/dev-zone-ingress.mjs
@@ -6,7 +6,7 @@ export const ZONE_BACKENDS = Object.freeze({
blog: Object.freeze({ hostname: "127.0.0.1", port: 3002 }),
})
-export const BLOG_ROUTE_PREFIXES = Object.freeze(["/blog", "/og/blog"])
+export const BLOG_ROUTE_PREFIXES = Object.freeze(["/blog", "/og/blog", "/guides"])
export function selectZone(pathname) {
return BLOG_ROUTE_PREFIXES.some((prefix) => pathname.startsWith(prefix))
diff --git a/src/web/scripts/dev-zone-ingress.test.ts b/src/web/scripts/dev-zone-ingress.test.ts
index 0b30c67ad..be97abb80 100644
--- a/src/web/scripts/dev-zone-ingress.test.ts
+++ b/src/web/scripts/dev-zone-ingress.test.ts
@@ -27,7 +27,7 @@ async function listen(server: http.Server): Promise<number> {
describe("development zone selection", () => {
it("matches the approved Cloudflare route prefixes exactly", () => {
- expect(BLOG_ROUTE_PREFIXES).toEqual(["/blog", "/og/blog"])
+ expect(BLOG_ROUTE_PREFIXES).toEqual(["/blog", "/og/blog", "/guides"])
expect([
"/blog",
"/blog/post?draft=1",
@@ -35,6 +35,8 @@ describe("development zone selection", () => {
"/blogger",
"/og/blog/post",
].map(selectZone)).toEqual(["blog", "blog", "blog", "blog", "blog"])
+ expect(["/guides", "/guides/", "/guides?topic=coding"].map(selectZone)).toEqual(["blog", "blog", "blog"])
+ expect(selectZone("/guides-other")).toBe("blog")
expect(["/", "/Blog", "/og/Blog", "/api/blog", "/_next/app.js"].map(selectZone)).toEqual([
"main",
"main",
diff --git a/src/web/scripts/verify-zone-output.test.ts b/src/web/scripts/verify-zone-output.test.ts
index c26c9ce24..1309dc76a 100644
--- a/src/web/scripts/verify-zone-output.test.ts
+++ b/src/web/scripts/verify-zone-output.test.ts
@@ -12,6 +12,7 @@ const blogRoutes = {
},
}
const blogAppPaths = {
+ "/guides/page": "guides.js",
"/_not-found/page": "not-found.js",
"/blog/(index)/page": "index.js",
"/blog/[slug]/page": "post.js",
diff --git a/src/web/scripts/verify-zone-output.ts b/src/web/scripts/verify-zone-output.ts
index 72dbae478..937b6d391 100644
--- a/src/web/scripts/verify-zone-output.ts
+++ b/src/web/scripts/verify-zone-output.ts
@@ -27,7 +27,7 @@ export function verifyZoneManifests(args: {
}): void {
const mainRoutes = Object.keys(args.mainAppPaths)
assert(
- mainRoutes.every((route) => !route.startsWith("/blog") && !route.startsWith("/og/blog")),
+ mainRoutes.every((route) => !route.startsWith("/blog") && !route.startsWith("/og/blog") && !route.startsWith("/guides/")),
"Main Next output still owns a Blog route",
)
assert(
@@ -40,6 +40,7 @@ export function verifyZoneManifests(args: {
const blogRoutes = Object.keys(args.blogAppPaths)
for (const required of [
"/blog/(index)/page",
+ "/guides/page",
"/blog/[slug]/page",
"/blog/feed.xml/route",
"/og/blog/[slug]/route",
@@ -49,6 +50,7 @@ export function verifyZoneManifests(args: {
}
assert(
blogRoutes.every((route) => (
+ route === "/guides/page" ||
route.startsWith("/blog") ||
route.startsWith("/og/blog") ||
route.startsWith("/internal/blog-discovery") ||
diff --git a/src/web/src/components/public-layout.test.tsx b/src/web/src/components/public-layout.dom.test.tsx
similarity index 62%
rename from src/web/src/components/public-layout.test.tsx
rename to src/web/src/components/public-layout.dom.test.tsx
index c0be93ed1..72565c4b8 100644
--- a/src/web/src/components/public-layout.test.tsx
+++ b/src/web/src/components/public-layout.dom.test.tsx
@@ -1,5 +1,5 @@
import React from "react"
-import { renderToStaticMarkup } from "react-dom/server"
+import { render } from "@/test/react-dom-harness"
import { describe, expect, it, vi } from "vitest"
vi.mock("next/link", () => ({
@@ -15,6 +15,9 @@ import { isCrossZoneNavigation, PublicLayout } from "./public-layout"
describe("PublicLayout zone navigation", () => {
it("classifies only document transitions across Worker ownership", () => {
+ expect(isCrossZoneNavigation("/guides#coding-agents", "main")).toBe(true)
+ expect(isCrossZoneNavigation("/guides/", "blog")).toBe(false)
+ expect(isCrossZoneNavigation("/guides-other", "main")).toBe(true)
expect(isCrossZoneNavigation("/blog", "main")).toBe(true)
expect(isCrossZoneNavigation("/blogger", "main")).toBe(true)
expect(isCrossZoneNavigation("/templates", "main")).toBe(false)
@@ -25,25 +28,25 @@ describe("PublicLayout zone navigation", () => {
})
it("uses hard anchors for Blog-to-main and Next links within Blog", () => {
- const html = renderToStaticMarkup(
+ const { container } = render(
<PublicLayout zone="blog" breadcrumb="Blog" footer="rich">
content
</PublicLayout>,
)
- expect(html).toContain('<a href="/" class="flex items-center gap-1">')
- expect(html).toContain('data-next-link="true" href="/blog"')
- expect(html).toContain('<a href="/templates"')
- expect(html).toContain('<a href="/llms.txt"')
+ expect(container.innerHTML).toContain('<a href="/" class="flex items-center gap-1">')
+ expect(container.innerHTML).toContain('data-next-link="true" href="/blog"')
+ expect(container.innerHTML).toContain('<a href="/templates"')
+ expect(container.innerHTML).toContain('<a href="/llms.txt"')
})
it("uses hard anchors for main-to-Blog and Next links within main", () => {
- const html = renderToStaticMarkup(
+ const { container } = render(
<PublicLayout zone="main" footer="rich">content</PublicLayout>,
)
- expect(html).toContain('data-next-link="true" href="/"')
- expect(html).toContain('<a href="/blog"')
- expect(html).toContain('data-next-link="true" href="/templates"')
+ expect(container.innerHTML).toContain('data-next-link="true" href="/"')
+ expect(container.innerHTML).toContain('<a href="/blog"')
+ expect(container.innerHTML).toContain('data-next-link="true" href="/templates"')
})
})
diff --git a/src/web/src/components/public-layout.tsx b/src/web/src/components/public-layout.tsx
index b3af66fe6..d7eb95145 100644
--- a/src/web/src/components/public-layout.tsx
+++ b/src/web/src/components/public-layout.tsx
@@ -17,7 +17,7 @@ export type PublicZone = "main" | "blog";
export function isCrossZoneNavigation(href: string, zone: PublicZone): boolean {
if (!href.startsWith("/")) return false;
- const blogOwned = href.startsWith("/blog") || href.startsWith("/og/blog");
+ const blogOwned = href.startsWith("/blog") || href.startsWith("/og/blog") || href.startsWith("/guides");
return zone === "main" ? blogOwned : !blogOwned;
}
diff --git a/src/web/src/lib/observability/coverage.ts b/src/web/src/lib/observability/coverage.ts
index 699ec2fa8..fa095df6a 100644
--- a/src/web/src/lib/observability/coverage.ts
+++ b/src/web/src/lib/observability/coverage.ts
@@ -15,6 +15,7 @@ export const pageRoutes = [
"/c/onboarding-preview",
"/contact",
"/device",
+ "/guides",
"/landing-legacy",
"/onboarding-preview",
"/pricing",
diff --git a/src/web/src/lib/root-sitemap.test.ts b/src/web/src/lib/root-sitemap.test.ts
index 899a9cc68..404c888ff 100644
--- a/src/web/src/lib/root-sitemap.test.ts
+++ b/src/web/src/lib/root-sitemap.test.ts
@@ -38,6 +38,7 @@ describe("sitemap", () => {
expect(urls).toContain("https://alook.ai/pricing");
expect(urls).not.toContain("https://alook.ai/pricing-concept");
expect(urls).toContain("https://alook.ai/blog");
+ expect(urls).toContain("https://alook.ai/guides");
expect(urls).toContain("https://alook.ai/privacy");
expect(urls).toContain("https://alook.ai/blog/revised");
expect(urls).not.toContain("https://alook.ai/sign-in");
@@ -86,6 +87,7 @@ describe("sitemap", () => {
const urls = buildRootSitemap(null).map((entry) => entry.url);
expect(urls).not.toContain("https://alook.ai/blog");
+ expect(urls).not.toContain("https://alook.ai/guides");
expect(urls).toContain("https://alook.ai/privacy");
});
diff --git a/src/web/src/lib/root-sitemap.ts b/src/web/src/lib/root-sitemap.ts
index 67dbe0d91..733fe41d7 100644
--- a/src/web/src/lib/root-sitemap.ts
+++ b/src/web/src/lib/root-sitemap.ts
@@ -35,6 +35,7 @@ export function buildRootSitemap(manifest: BlogDiscoveryManifestV1 | null): Meta
priority: 0.8,
}]
: []),
+ ...(manifest ? [{ url: `${SITE_URL}/guides`, changeFrequency: "weekly" as const, priority: 0.6 }] : []),
...blogEntries,
{ url: `${SITE_URL}/contact`, changeFrequency: "monthly", priority: 0.5 },
{ url: `${SITE_URL}/privacy`, changeFrequency: "yearly", priority: 0.3 },