Conversation
Wiki generation is multi-page and tool-call-heavy; host platforms like Factory may rate-limit mid-session and discard unwritten analysis held in context. Mirror the research workflow's crash-safe persistence rules: write each page immediately after reading its source, create phased checkpoint tasks via the host task system, and exit cleanly with a resume protocol on interrupt. Extract shared durability fragments into workflow-persistence.ts so future workflows can reuse the same host-agnostic guidance.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
🟡 Changes recommended
A couple of small but concrete issues in the newly added durability guidance/tests (including a non-actionable exec("cat …") placeholder and a likely string-style mismatch) should be corrected to ensure the guide is copy/paste-safe and consistent with repo conventions.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds reusable, tool-agnostic durability guidance for the workflow({ kind: "wiki" }) guide so long, multi-page wiki generation can survive host rate limits/session interruptions by persisting progress incrementally and resuming cleanly.
Changes:
- Introduces shared “persist as you go”, “checkpoint tasks”, and “session interrupt recovery” markdown fragments for workflows.
- Integrates the new durability fragments into the wiki workflow body and updates the codebase-wiki pack skill guidance accordingly.
- Adds targeted tests to lock in the new guide fragments and asserts the wiki workflow plan includes the durability sections.
File summaries
| File | Description |
|---|---|
| packages/server/src/mcp/tools/workflow.test.ts | Extends the wiki workflow plan test to assert the new persistence/recovery guidance is present. |
| packages/server/src/mcp/tools/workflow-persistence.ts | Adds shared durability/persistence markdown fragments for workflow bodies. |
| packages/server/src/mcp/tools/workflow-persistence.test.ts | Adds unit tests for the new persistence fragment helpers. |
| packages/server/src/mcp/tools/wiki-body.ts | Injects the new persistence/recovery sections into the wiki workflow guide body. |
| packages/server/assets/skills/packs/codebase-wiki/SKILL.md | Updates pack guidance to emphasize incremental persistence and resuming the workflow. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| expect(section).toContain('PERSIST AS YOU GO'); | ||
| expect(section).toContain('write` each page immediately'); | ||
| expect(section).toContain('content/wiki'); |
There was a problem hiding this comment.
Accepted — updated the assertion to match the exact guide substring write` each page immediately after reading its source so it tracks the formatted tool name rather than a partial backtick fragment.
| /** How to refer to the host's durable task/todo system without naming one product. */ | ||
| export function hostTaskSystemPhrase(): string { | ||
| return "your host's task system (`TaskCreate` in Claude; equivalent task/todo APIs elsewhere — Cursor, Factory, etc.)"; | ||
| } |
There was a problem hiding this comment.
Accepted on both points. Doc comment now reads "without requiring a single host product" (examples are fine; mandating one host is not). Return string switched to single quotes with an escaped apostrophe to match neighboring files.
| - **After each page lands, update OVERVIEW nav links if needed** — don't defer all hub updates to Phase 7. | ||
| - **Structured notes that live only in your context are not persisted work** — if a section is worth keeping, it belongs in a wiki page via \`write\`/\`edit\`, not in chat or memory. | ||
|
|
||
| On resume after any interrupt: re-invoke \`workflow({ kind: "wiki" })\`, inventory partial progress with \`exec("find ${contentDir}/wiki -name '*.md'")\` (or \`exec("ls -R ${contentDir}/wiki")\`), read each partial page via \`exec("cat …")\`, skip completed pages, continue from the first gap in phase order.`; |
There was a problem hiding this comment.
Accepted — replaced the Unicode ellipsis with a concrete example: exec("cat ${contentDir}/wiki/modules/.md") plus "substitute the actual path" so agents get a copy-pasteable shape during resume.
- Stabilize test assertion to match exact guide substring
- Clarify hostTaskSystemPhrase doc comment; use single-quote style
- Replace non-actionable exec("cat …") with concrete example path
Copilot review adjudicationAll three Copilot comments were valid and are addressed in
Tests re-run: 13/13 pass. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5246c13621
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ⛔ **PERSIST AS YOU GO — crash-safe checkpoint rule.** Wiki generation is multi-page and tool-call-heavy. Host platforms may rate-limit or terminate sessions mid-run. The most expensive failure is completed analysis held in context, never written — discarded when the session died. The knowledge base is the checkpoint; these rules make every phase crash-safe: | ||
|
|
||
| - **Create \`wiki/OVERVIEW.md\` skeleton early (Phase 2)** — stamp \`profile\` + \`source_commit\` + a nav map (placeholder links are fine) before module pages. Fill sections as you go; don't defer the whole hub to the end. |
There was a problem hiding this comment.
When generation is interrupted after Phase 2, this instruction has already stamped source_commit; on the next invocation, buildWikiBody classifies every stamped OVERVIEW as REFRESH, where an unchanged source_commit..HEAD diff produces no affected pages. Consequently, the newly promised resume path skips unfinished architecture/module/flow/concept phases instead of continuing them. Keep a distinct completion marker, leave source_commit empty until Phase 7, or make mode detection recognize a partial generation.
Useful? React with 👍 / 👎.
|
|
||
| Don't free-hand it — call **`workflow({ kind: "wiki" })`** and follow the phased, STOP-gated guide. It auto-detects mode: a stubbed `OVERVIEW.md` (empty `source_commit`) → **generate** (survey → overview → architecture → modules → flows → concepts → link-graph audit); a stamped `source_commit` → **refresh** (diff `source_commit..HEAD`, update only affected pages, re-stamp). | ||
|
|
||
| **Persist incrementally (MUST).** Wiki generation is multi-page and tool-call-heavy — host platforms (Factory, Cursor, Claude, etc.) may rate-limit or end sessions mid-run. Write each page immediately after reading its source; never hold finished module write-ups in context for a trailing batch. The workflow guide carries the full crash-safe + resume rules; re-invoking `workflow({ kind: "wiki" })` picks up from partial pages already in `wiki/`. |
There was a problem hiding this comment.
This changes the installed Codebase Wiki skill and the runtime guidance returned by workflow({ kind: "wiki" }), but the commit contains no .changeset file. Add the required patch changeset so the user-visible behavior is versioned and included in release notes.
AGENTS.md reference: AGENTS.md:L167-L172
Useful? React with 👍 / 👎.
|
|
||
| Don't free-hand it — call **`workflow({ kind: "wiki" })`** and follow the phased, STOP-gated guide. It auto-detects mode: a stubbed `OVERVIEW.md` (empty `source_commit`) → **generate** (survey → overview → architecture → modules → flows → concepts → link-graph audit); a stamped `source_commit` → **refresh** (diff `source_commit..HEAD`, update only affected pages, re-stamp). | ||
|
|
||
| **Persist incrementally (MUST).** Wiki generation is multi-page and tool-call-heavy — host platforms (Factory, Cursor, Claude, etc.) may rate-limit or end sessions mid-run. Write each page immediately after reading its source; never hold finished module write-ups in context for a trailing batch. The workflow guide carries the full crash-safe + resume rules; re-invoking `workflow({ kind: "wiki" })` picks up from partial pages already in `wiki/`. |
There was a problem hiding this comment.
Existing projects will not be offered this updated persistence guidance because the bundled SKILL.md still reports version 0.18.0, the same version as before this commit. computePackUpdateStatus only sets updateAvailable when the bundled version is strictly greater than the installed version, so users with the prior 0.18.0 pack remain on the old body even after upgrading SynapseNote. Increment the pack version with this content change.
Useful? React with 👍 / 👎.
| const taskPhrase = hostTaskSystemPhrase(); | ||
| return `## Step 0 — Create workflow checkpoint tasks (GENERATE mode) | ||
|
|
||
| ⛔ **ALWAYS THE FIRST ACTION** after mode detection confirms GENERATE (stub \`source_commit\`). Before any survey read or wiki write — create tasks via ${taskPhrase}. They persist across context compaction, make skipped phases visible, and show progress to the user. |
There was a problem hiding this comment.
On an MCP client without a durable task/todo API, GENERATE cannot perform this mandatory “ALWAYS THE FIRST ACTION” step: the only concrete operation shown is Claude's TaskCreate, and the guide also requires blocked-by relationships that a generic plan facility may not support. Because the surrounding fragment explicitly targets any host, such clients are instructed to invoke nonexistent tools before doing any useful work. Condition this step on task-system availability and provide a no-task fallback.
Useful? React with 👍 / 👎.
|
Gentle re-review ping — Copilot durability-guide notes are addressed on tip (exact assert, clarified host phrase, concrete exec example). Happy to iterate. |
What & why
Wiki generation (
workflow({ kind: "wiki" })) is multi-page and tool-call-heavy. When host platforms like Factory rate-limit or end sessions mid-run, agents were holding completed analysis in context and losing it — the research workflow already had crash-safe persistence rules, but the wiki guide did not.This adds tool-agnostic durability guidance (not Factory-specific code):
checkpoint(), resume by re-invoking the wiki workflowShared fragments live in
workflow-persistence.tsfor reuse across workflows.How this was verified
bun test packages/server/src/mcp/tools/workflow.test.ts packages/server/src/mcp/tools/workflow-persistence.test.ts— 13 passChecklist
codebase-wikipack skill pointer)