Rewrite promptforge and harness facade docs as task tours - #102
Merged
Merged
Conversation
A host can now name `Origin` through the `harness` crate, and the doc examples can run a host on tokio. The `vfs` module in `crates/harness/src/lib.rs` re-exports `promptforge::vfs::Origin` beside `VfsError` and `VfsRef`. `crates/harness/Cargo.toml` adds `tokio` with the `signal` feature under `[dev-dependencies]`, and `Cargo.lock` records it. - `tokio` is a dev-dependency only, with `workspace = true`. The normal dependencies of the crate do not change. - The re-export adds `Origin` to the public surface of the `vfs` module. - No test, doc example, or `.md` page changes in this commit.
The `promptforge` and `harness` facade crates get rustdoc pages that teach a new reader by task, and a new tool writes and checks these pages. `tools/cicerone.md` and the scripts under `tools/cicerone/scripts/` replace `tools/dokuman-facade.md` and `tools/scripts/`. Each page under `crates/promptforge/src/` and `crates/harness/src/` becomes a set of task tours with doc examples and a `Reference` section.
- `tools/cicerone.md` splits the work between agents: collectors read the source, curators write a brief, and a writer that never sees the source writes each page from the brief and a compiled skeleton. A cold reader then checks each page.
- `tools/cicerone/plans/promptforge.md` and `tools/cicerone/plans/harness.md` set the reader and one running example for each crate: `greeter` for `promptforge` and `desk` for `harness`.
- `AGENTS.md` adds a rule: a change to a public item of `promptforge` or `harness` runs `tools/cicerone.md` in update mode for that crate before merge.
- `tools/scripts/build_coverage.py` moves to `tools/cicerone/scripts/inventory.py`. All other files under `tools/scripts/` are removed. The scripts write their work files under `target/cicerone-CRATE/`.
- The `harness` doc examples import `harness::vfs::{Origin, VfsRef}`, and `crates/harness/src/cancel.md` tells the reader to await `tokio::signal::ctrl_c`.
- No `.rs`, `Cargo.toml`, or test file changes. The Python scripts have no tests in this commit.
vinniefalco
changed the title
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
promptforgeandharnessfacade crates get rustdoc pages rewritten as task tours for a Rust developer new to the project. A new doc tool, Cicerone (tools/cicerone.md,tools/cicerone/), replaces the Dokuman tool; it writes the pages and checks them against the source. The one code change, inharness, is small and additive.Commits
54ed626Re-exportOriginfromvfsand addtokiodev-dependency.harness::vfsre-exportspromptforge::vfs::Origin, andtokiowithsignalis added under[dev-dependencies]only. It comes first because the doc examples depend on it.be36e07Replace Dokuman with Cicerone and rewrite facade doc pages. Addstools/cicerone.mdwith its plans and scripts, removestools/dokuman-facade.mdandtools/scripts/, and rewrites every.mdpage undercrates/promptforge/src/andcrates/harness/src/. No.rs,Cargo.toml, or test changes.How the pages were checked
cargo doc -p <crate> --no-depswith-D warnings, and the doctests.promptforge: 87 of 94 across the 13 module pages. That report giveslib.mdno score; its audit corrections were applied by hand and it passes the gates.harness: 37 of 40.lib.md18/19 andlog.md6/7 (first report),cancel.md7/7 (second),vfs.md6/7 (third).How to review
crates/promptforge/src/lib.mdandcrates/harness/src/lib.mdfirst.Bugs found while writing the docs
Filed as separate issues, not fixed here.
Closedafter a cancel or rebind even though the session goes on.display_chaindrops a cause whose text appears in an outer message.set_catalogat generation 0.vfs::Statandvfs::Entryhave no constructor, so outside crates cannot implementVfsAccess.Rule change
AGENTS.mdnow asks that a change to a public item ofpromptforgeorharnessruntools/cicerone.mdin update mode before merge.