GuideForge

Writing tutorials that actually work is harder than writing the code itself. Most guides rot the moment a library updates, leave beginners stranded with undefined terms, or fail to provide a way for readers to verify their progress.

What it does

• Plans guides by modeling the target audience and building a milestone ladder based on runnable vertical slices.
• Scaffolds documentation using a canonical layout including stack definitions, progress trackers, and feedback logs.
• Drafts milestones into atomic steps that teach the "why" alongside the "how" while defining terms as they appear.
• Audits and modernizes existing READMEs or tutorials by verifying library versions and identifying instructional gaps.
• Manages execution by diffing a reader's workspace against guide steps to verify work and log friction points.

How it works

1. Initiate a phase like plan-guide or modernize-guide by providing an idea or an existing codebase.
2. Review the plan in the generated guide/PLAN.md and approve the milestone structure.
3. Execute drafting using draft-milestone to generate the step-by-step teaching files and verification tests.
4. Maintain the guide using update-stack or report-issue to handle framework updates or reader feedback.

Frameworks & tools

This tool is stack-agnostic and works for web apps, APIs, CLIs, libraries, and games. It integrates with your local file system to read project code and write Markdown documentation.

Why this beats prompting it yourself

Generic prompts often produce "happy path" tutorials that break on the first error or skip crucial environmental setup. This skill enforces a gated pedagogical method that ensures every milestone has a testable acceptance criteria and verified library versions.

Use cases

• Convert a messy internal README into a formal developer onboarding guide.
• Draft a QA test suite for a tester to follow based on a new codebase.
• Update a stale tutorial to work with the latest versions of Next.js or FastAPI.
• Create a "build-along" course for a new open-source library.

Known limitations

Requires manual approval at specific gates to ensure instructional accuracy. It cannot browse the web if the host environment lacks a browser tool, requiring manual version verification in those cases.