Repository navigation
Expand file tree
/
Copy pathreading-queue.html
More file actions
19 lines (19 loc) · 25.5 KB
/
Copy pathreading-queue.html
File metadata and controls
19 lines (19 loc) · 25.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="A runnable Context Docs example: develop a Reading Queue feature across sessions, maintain decisions and source-linked context, then optionally deploy your own Cloudflare Workers and D1 app.">
<meta name="theme-color" content="#f7f9f8"><meta property="og:title" content="A runnable Context Docs example: Reading Queue"><meta property="og:description" content="One small app, a real change and a context handoff. Follow the step-by-step worked example."><meta property="og:type" content="website"><meta property="og:url" content="{{SITE_URL}}reading-queue/"><meta property="og:image" content="{{SITE_URL}}context-docs-overview.png">
<title>Reading Queue: a runnable Context Docs example</title><link rel="canonical" href="{{SITE_URL}}reading-queue/"><link rel="icon" href="../favicon.svg" type="image/svg+xml"><link rel="stylesheet" href="../styles.css"><script src="../main.js" defer></script></head>
<body class="guide-page example-page"><a class="skip-link" href="#main">Skip to content</a>
<header class="site-header wrap"><a class="brand" href="../" aria-label="Context Docs home"><span class="brand-mark" aria-hidden="true">c<span>_</span></span>Context Docs</a><nav aria-label="Main navigation"><a href="../getting-started/">Guide</a><a href="../compare/">Compare</a><a href="https://github.com/jaredchu/context-docs-example-reading-queue">Example source <span aria-hidden="true">↗</span></a></nav></header>
<main id="main" class="wrap"><header class="guide-hero"><p class="eyebrow">A RUNNABLE WORKED EXAMPLE</p><h1>One small app.<br><span>A useful handoff.</span></h1><p class="guide-lead">Build a Reading Queue feature across sessions. Keep the requirement, decision, checks and next action findable in Markdown. Local practice is complete on its own; deploying your own copy on Cloudflare is optional.</p><p class="guide-meta">For Codex and Claude Code · Authored teaching example<br>Workers + D1 belong to the app; Context Docs itself needs neither.</p><p><a href="https://context-docs-example-reading-queue.viweb.workers.dev">Try the live app</a> · <a href="https://github.com/jaredchu/context-docs-example-reading-queue">Browse the separate GitHub project</a></p></header>
<div class="guide-layout"><nav class="guide-toc" aria-label="On this page"><p class="eyebrow">WORK THROUGH IT</p><ol><li><a href="#try">Try the app first.</a></li><li><a href="#run">Run the starter locally.</a></li><li><a href="#adopt">Inspect the existing context setup.</a></li><li><a href="#read">Follow the sources, then audit.</a></li><li><a href="#scope">Make the next change explicit.</a></li><li><a href="#save">Leave a useful handoff.</a></li><li><a href="#resume">Resume in a fresh session.</a></li><li><a href="#verify">Verify behavior and the saved state.</a></li><li><a href="#compare">Compare with the completed example.</a></li><li><a href="#deploy">Deploy your own fork, if you want.</a></li><li><a href="#takeaways">Know what this example demonstrates.</a></li></ol></nav><article class="guide-content" aria-label="Reading Queue walkthrough"><section id="try" class="guide-section"><p class="eyebrow">STEP 01</p><h2>Try the app first.</h2><p>Open the <a href="https://context-docs-example-reading-queue.viweb.workers.dev">live Reading Queue</a>, add two public links, mark one as read and try the Unread filter. Export JSON downloads the whole active queue, including read links hidden by the filter.</p><p>This is a disposable demo. Your browser receives a random HttpOnly cookie identifying a queue of up to 20 links. Links expire within 24 hours; expired rows are removed on writes and by a daily cleanup. It is not account-authenticated private storage. Use public example URLs only. Cookie loss loses access; there is no cross-device sync or recovery.</p></section><section id="run" class="guide-section"><p class="eyebrow">STEP 02</p><h2>Run the starter locally.</h2><p>You need Git, Node.js 22 or later, npm, and Codex or Claude Code for the context exercise. CI uses Node 24. A Cloudflare account is needed only if you choose to deploy your own copy.</p><p>Clone the example and create a working branch from the starter tag. The starter already supports adding, reading, filtering and deleting links; JSON export is the pending change.</p><div class="code-block"><pre tabindex="0" aria-label="Run the starter locally"><code>git clone https://github.com/jaredchu/context-docs-example-reading-queue.git
cd context-docs-example-reading-queue
git switch -c try-export tutorial-start
npm ci
npm run db:local
npm run dev</code></pre></div><p>Open the localhost URL printed by Wrangler. Keep that terminal running; use a second terminal for tests and Git. Local D1 data is stored under the ignored <code>.wrangler/</code> directory. It is separate from the public demo and your remote database.</p><h3>Prompt: Run the starter</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-run" data-status="status-run" data-destination="your coding agent" hidden aria-label="Copy run the starter prompt">Copy</button><pre tabindex="0" aria-label="Run the starter prompt"><code id="prompt-run">Confirm this is the Reading Queue example folder. Install its locked npm dependencies, apply only local D1 migrations, run the existing tests, and start the local dev server. Report the local URL and any failures. Do not create cloud resources or deploy.</code></pre></div><p id="status-run" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> The baseline app works locally and the baseline test result is recorded honestly.</p><p><strong>Check:</strong> Open the printed localhost URL and inspect the test output. No remote resource is required.</p></section><section id="adopt" class="guide-section"><p class="eyebrow">STEP 03</p><h2>Inspect the existing context setup.</h2><p>If the two skills are not installed, follow the <a href="../getting-started/#install">installation guide</a> first. This example does not install or update them for you. Open the cloned example folder in your coding agent. Name the adoption skill once here. The later prompts are ordinary work requests: the loaded project rule owns ongoing maintenance.</p><p>Run <code>$adopt-context-docs</code> in Codex or <code>/adopt-context-docs</code> in Claude Code. The starter already has a context entry point and maintenance rule: check that adoption reuses that setup; decline a second layout. For your own unconfigured project, adoption can establish those pieces.</p><p>Inspect <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/tutorial-start/AGENTS.md">AGENTS.md</a>, the <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/tutorial-start/CLAUDE.md">Claude import</a>, and <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/tutorial-start/docs/project-context.md">project context</a>. Check <code>git status --short</code> and inspect the adoption diff. The marker records adoption intent. Verify which instruction file your client actually loads; presence alone does not establish automatic loading. Keep optional logging off for this exercise.</p><h3>Prompt: Adopt once</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-adopt" data-status="status-adopt" data-destination="your coding agent" hidden aria-label="Copy adopt once prompt">Copy</button><pre tabindex="0" aria-label="Adopt once prompt"><code id="prompt-adopt">Use adopt-context-docs to inspect and reuse this project’s existing context documents and maintenance rule. Preserve the current layout, decisions and evidence. Keep optional logging off. Show which instructions should load in this client and any loading uncertainty. Do not deploy or change global settings.</code></pre></div><p id="status-adopt" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> One reused context entry point and maintenance rule, with configuration and loading kept distinct.</p><p><strong>Check:</strong> Inspect AGENTS.md, CLAUDE.md and the resulting diff; no duplicate layout or logging setup.</p></section><section id="read" class="guide-section"><p class="eyebrow">STEP 04</p><h2>Follow the sources, then audit.</h2><p>The entry point should give the purpose, current state, unfinished work and next action. Follow its links to <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/main/docs/decisions.md">decisions</a>, the <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/main/docs/export-requirement.md">export requirement</a>, code and tests. You do not need to paste a previous chat.</p><p>An audit reports findings; a separate maintenance request authorizes repairs. Do not count an audit as a successful implementation or turn a proposal into an approved owner decision.</p><p>To check that the audit left files unchanged, compare file contents before and after, not only <code>git status --short</code> categories: a file already marked modified can change again without its status changing. Start from a clean checkout, or before the audit save the <code>git diff</code> output plus copies or checksums of already-modified and relevant untracked files outside the checkout, then compare afterwards. <code>git diff</code> shows tracked changes only; status lists untracked files without comparing their contents and omits ignored files.</p><h3>Prompt: Audit without edits</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-read" data-status="status-read" data-destination="your coding agent" hidden aria-label="Copy audit without edits prompt">Copy</button><pre tabindex="0" aria-label="Audit without edits prompt"><code id="prompt-read">Audit this project’s saved context against its README, linked decisions, export requirement, source and tests. Report concrete inaccuracies, unsupported claims and missing next steps with source locations. Leave files unchanged.</code></pre></div><p id="status-read" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> Source-linked findings with no file edits.</p><p><strong>Check:</strong> Compare before/after diffs or snapshots of the files in scope; unchanged status alone is not enough.</p></section><section id="scope" class="guide-section"><p class="eyebrow">STEP 05</p><h2>Make the next change explicit.</h2><p>The worked requirement is small: export every active link in the current browser's queue as JSON, regardless of the selected filter. Do not export cookie values, session identifiers or database/account metadata. An empty queue should export <code>{"schema_version":1,"items":[]}</code>. A failed fetch must show an error without downloading a file.</p><p>The implementation team selected this exercise. The <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/main/docs/export-requirement.md">requirement file</a> is its source; it is not a transcript of an owner request. The decision to export the whole queue, rather than only filtered rows, belongs in the decision note with its rationale. No schema change or new cloud service is needed.</p><p>The linked main-branch requirement and decision include October 26 wording clarifications. The retained starter and completed tags keep their original documents. Use the versioned empty shape above; the decision clarification explains why changing a UI filter does not change export scope.</p><h3>Prompt: Scope the feature</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-scope" data-status="status-scope" data-destination="your coding agent" hidden aria-label="Copy scope the feature prompt">Copy</button><pre tabindex="0" aria-label="Scope the feature prompt"><code id="prompt-scope">Plan the pending JSON export change using the existing requirement. Identify the affected code and meaningful tests. Preserve whole-queue export regardless of the UI filter, browser isolation and expiry. Explain any unresolved decision. Do not implement or deploy yet.</code></pre></div><p id="status-scope" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> A bounded export plan using the requirement already in the repository.</p><p><strong>Check:</strong> The plan preserves privacy boundaries and requires no schema change or new service.</p></section><section id="save" class="guide-section"><p class="eyebrow">STEP 06</p><h2>Leave a useful handoff.</h2><p>The loaded maintenance rule is intended to guide updates after meaningful work without naming the skill each time. An explicit handoff request is still useful when you are about to stop. Before changing code, ask for a focused context update. Preserve the baseline's check results with their actual scope; do not describe the pending export as complete.</p><p>Review the diff. A useful handoff says that CRUD and filtering exist, export is pending, the full active queue is required, and the next step is implementation plus export tests. Test counts and results must come from your run, not this tutorial.</p><h3>Prompt: Prepare the handoff</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-save" data-status="status-save" data-destination="your coding agent" hidden aria-label="Copy prepare the handoff prompt">Copy</button><pre tabindex="0" aria-label="Prepare the handoff prompt"><code id="prompt-save">Save the agreed export plan and next action in the existing project documents. Preserve the requirement, decision authority and source links. Separate implemented behavior, checks actually run and pending work; keep the existing progress view current. Do not implement export or deploy.</code></pre></div><p id="status-save" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> A concise handoff that keeps export pending and names its next action.</p><p><strong>Check:</strong> Read the context diff; no claimed check may exceed the observed result.</p></section><section id="resume" class="guide-section"><p class="eyebrow">STEP 07</p><h2>Resume in a fresh session.</h2><p>Start a new agent session in the same example folder. Use a supported client and confirm the intended project. The ordinary prompt below does not name the skill or ask for a documentation update. Check the resulting Markdown diff; if it is missed, retain that outcome. Explicitly asking the agent to read the entry point is a fallback when loading is unconfirmed.</p><p>A genuinely new conversation can test the handoff immediately; no waiting period is needed. Native memory, such as Claude Code auto memory or Codex memories, can also contribute to what a fresh session knows. Keep your usual settings for ordinary use. For a diagnostic exercise, record your client's memory and instruction-loading settings and inspect which sources the agent actually read.</p><p>The agent still needs to inspect implementation details. Saved context provides a starting point and source map; it does not replace code review, testing or deployment authorization. When two sessions share a document, agree on one writer.</p><h3>Prompt: Implement in a fresh session</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-resume" data-status="status-resume" data-destination="your coding agent" hidden aria-label="Copy implement in a fresh session prompt">Copy</button><pre tabindex="0" aria-label="Implement in a fresh session prompt"><code id="prompt-resume">Implement the pending JSON export feature using the existing requirements. Preserve the temporary demo’s browser isolation and expiry behavior. Verify the change with the available local tests. Do not install packages, deploy, provision services, publish, or change files outside this project.</code></pre></div><p id="status-resume" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> Export is implemented and relevant context reflects the meaningful change.</p><p><strong>Check:</strong> Inspect both code and Markdown diffs. If maintenance is missed, report the miss and ask for a focused repair.</p></section><aside class="guide-note"><strong>Observed with an ordinary prompt</strong><p>On <time datetime="2026-10-25">October 25, 2026</time>, in one fresh Claude Code run with Opus 5.5 at High, the implementation prompt above named no skill and requested no documentation update. With the repository maintenance instructions and installed core 0.2.6 available, the agent invoked <code>context-docs</code> and updated three context documents. It kept browser verification pending; the fixture's 20 API tests passed on the coordinator's rerun. <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/main/docs/evidence/README.md">Read the exact prompt, Markdown diff and limits</a>. The retained decision text has an overbroad identifier claim, called out in the evidence; the update still needs review.</p><p>This is one maintainer-run observation, separate from the published app's 18 tests. That run disabled Claude Code auto memory as a diagnostic condition, not a recommended everyday setting. The October 25 case covered only this Claude implementation step; it included no Codex run. The other walkthrough prompts were not exercised in that case. It does not establish dependable implicit selection, better handoffs or effort savings.</p><p><strong>Later Codex trial.</strong> A maintainer-operated Codex CLI trial with GPT 6.1 Sol at High used preinstalled skills and the starter's adopted AGENTS.md rule, with user configuration and execution-policy rules ignored. Eight unchanged local prompts ran across two threads, including a new implementation thread. The agent read the installed skill and updated context without another reminder; 23 fixture tests passed. Native browser launches failed; separate coordinator Chrome checks passed after helper corrections. Verification downloaded BrowserAct support despite the no-install constraint, then removed it. This is not a clean walkthrough pass, independent learner validation, evidence that the skill caused a benefit, or broad implicit-selection proof. <a href="https://github.com/jaredchu/context-docs/blob/main/docs/reading-queue-example.md#scope-and-status">Read the trial's scope and status</a>.</p></aside><section id="verify" class="guide-section"><p class="eyebrow">STEP 08</p><h2>Verify behavior and the saved state.</h2><div class="code-block"><pre tabindex="0" aria-label="Validate the change"><code>npm test
npx wrangler deploy --dry-run --outdir .local/build
git diff --check
git diff</code></pre></div><p>The API suite uses workerd and a local D1 database. These are application checks, not an evaluation of Context Docs. In your browser, add two links, mark one read, select Unread and export: the downloaded JSON should include both links. Use a separate browser context to check queue isolation. Test an empty queue and simulate a failed export request: show an error and produce no file.</p><p>After verification, review the context diff. Does it say what changed, cite the tests actually run, preserve decisions and remaining limits, and give the next action? Keep detailed diagnostic output out of shared context unless the next reader needs it.</p><h3>Prompt: Verify the result</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-verify" data-status="status-verify" data-destination="your coding agent" hidden aria-label="Copy verify the result prompt">Copy</button><pre tabindex="0" aria-label="Verify the result prompt"><code id="prompt-verify">Verify the export acceptance criteria and relevant existing behavior. Run the local tests and deployment dry run. Check the browser download, full-queue behavior under filtering, an empty queue and a failed request. Report what actually passed, failures and what remains untested. Do not deploy.</code></pre></div><p id="status-verify" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> Check results are separate from assumptions and untested behavior.</p><p><strong>Check:</strong> Inspect the downloaded JSON and confirm a failed request produces no file.</p></section><section id="compare" class="guide-section"><p class="eyebrow">STEP 09</p><h2>Compare with the completed example.</h2><p>Stop your dev server before switching revisions. To inspect the reference solution without replacing your work:</p><div class="code-block"><pre tabindex="0" aria-label="Compare starter and completed revisions"><code>git diff tutorial-start..tutorial-complete -- src public tests docs</code></pre></div><p>The <a href="https://github.com/jaredchu/context-docs-example-reading-queue/tree/tutorial-complete">completed tag</a> shows the app and its updated context together. Compare meaning and acceptance criteria, not exact model wording. These authored Git snapshots demonstrate a workflow; no controlled fresh-session performance study or savings claim is made.</p><h3>Prompt: Review the handoff</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-compare" data-status="status-compare" data-destination="your coding agent" hidden aria-label="Copy review the handoff prompt">Copy</button><pre tabindex="0" aria-label="Review the handoff prompt"><code id="prompt-compare">Review the implementation and saved project context together against the export requirement. Check retained decisions, evidence, remaining limits and the next action. Compare with the completed example if useful. Report findings without editing files or deploying.</code></pre></div><p id="status-compare" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> A review covering app behavior and whether the saved handoff remains useful.</p><p><strong>Check:</strong> Resolve verified findings; preserve uncertainty and existing evidence.</p></section><section id="deploy" class="guide-section"><p class="eyebrow">STEP 10</p><h2>Deploy your own fork, if you want.</h2><p>Local practice ends with a tested change and a reviewed handoff. Deployment is a separate choice. Follow the example's <a href="https://github.com/jaredchu/context-docs-example-reading-queue#deploy-your-own-copy">deployment instructions</a> to fork it, choose a unique Worker name and create your own D1 database. Workers serves the static UI and API; D1 persists the temporary queue. R2 adds no useful behavior for these URL records, so it is omitted.</p><p>The repository includes a <a href="https://github.com/jaredchu/context-docs-example-reading-queue/blob/main/.github/workflows/ci.yml">GitHub Actions workflow</a>: test pull requests without deployment credentials; on code pushes to main, test, apply migrations, deploy and verify the live commit. Configure your own account/database variables and dedicated deployment token in GitHub. Never copy a local OAuth login token or use the maintainer's database. Documentation-only record commits do not trigger another deployment.</p><p>Check Cloudflare's current <a href="https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/">GitHub Actions guide</a> and <a href="https://developers.cloudflare.com/d1/reference/migrations/">D1 migration guidance</a>. Quotas and account billing still apply. Stored-row caps do not bound traffic or total usage; this is a teaching sandbox with no production abuse protection.</p><h3>Prompt: Deploy your own fork</h3><div class="code-block prompt-block"><button class="copy-button" type="button" data-copy="prompt-deploy" data-status="status-deploy" data-destination="your coding agent" hidden aria-label="Copy deploy your own fork prompt">Copy</button><pre tabindex="0" aria-label="Deploy your own fork prompt"><code id="prompt-deploy">Deploy my own reviewed Reading Queue fork to my selected Cloudflare account. First confirm the repository, unique Worker name and database; ask for any missing target information. Use a dedicated deployment token stored as a GitHub secret, with the required account and database variables. Run checks before publishing, then verify the live commit and app behavior. Never reuse the maintainer’s database or copy a local OAuth token into CI.</code></pre></div><p id="status-deploy" class="copy-status" aria-live="polite"></p><p><strong>Expected result:</strong> Your own fork deploys automatically from trusted main-branch code after passing tests.</p><p><strong>Check:</strong> Compare the live revision with the commit and exercise your own sandbox. This step authorizes real cloud changes only when you choose to run it.</p></section><section id="takeaways" class="guide-section"><p class="eyebrow">STEP 11</p><h2>Know what this example demonstrates.</h2><p>You have exercised adoption/reuse, a source-linked entry point, a decision and scoped requirement, a concise progress view, read-only audit, meaningful maintenance and an explicit new-session handoff. Git retains the two revisions. Optional event logging stays off; not every project needs a journal.</p><p>Context Docs supplies reusable maintenance guidance for this work. A carefully maintained README, native agent instructions or built-in memory may already be enough for your project. The extra convention is useful when repeated sessions need to preserve project facts, decisions and unfinished work with traceable sources. See <a href="../compare/#fit-title">the fit and tradeoffs comparison</a>.</p></section></article></div></main>
<footer class="wrap guide-footer"><p><a href="../getting-started/">Installation and first-project guide</a> · <a href="../compare/">Compare approaches</a> · <a href="https://github.com/jaredchu/context-docs-example-reading-queue">Example source and MIT license</a></p></footer></body></html>