From Messy Docs to Structured Standards in One Install

William Warne

Software Engineer | Fractional CTO | Founder

Introduction

Repos that grow with AI-assisted development often end up with documentation everywhere: ad-hoc markdown, outdated READMEs, and no shared structure. The result? Your AI tools don't know what "good" looks like, and neither does the next developer. We wanted a single, low-friction way to fix that—without forcing a full restructure on day one. This post shows what we built and how it behaves: a documentation management pack plus a CLI, with a clear before/after and an option to improve your current setup or adopt the full methodology.

The Problem: Docs and AI Drift Apart

When docs live in random places and follow no common standard, Cursor and Claude have nothing to anchor on. You get inconsistent outputs, repeated mistakes, and "we'll clean it up later" that never happens. Many teams don't need a full documentation overhaul—they need standards and a path to get there without throwing away existing work.

Before vs After: What Changes When You Install

Before: A typical repo might have a mix of READMEs, a few markdown files in docs/ or the root, and no shared structure or methodology. AI suggestions are generic and don't follow your intended doc types or traceability.

After (full install): You get a standard layout (docs/01-concept-of-operations through docs/10-operational-procedures), draft templates with a built-in methodology section, and Cursor rules + skills + CLAUDE.md so the AI follows the same structure and order. One command installs everything; then you run ctx compile so the tooling is up to date.

After (review only): If you prefer to keep your current folder structure, you can install only the standards and checklists—rules, skills, methodology, and checklists—without creating docs/01–10 or any templates. You improve where you are instead of moving everything first.

[Screenshot: before — repo with scattered docs. Add image when publishing.]

[Screenshot: after — same repo with docs/01–10 and draft templates, or with only .cursor and CLAUDE.md for "review only". Add image when publishing.]

How It Works in Practice

  1. Install the pack — From a ZIP or via the context CLI: ctx pack install pack-01-documentation-management --zip <path>. For review-only, add: --install-option Flavour=ReviewOnly.
  2. Compile AI context — Run ctx compile --pack pack-01-documentation-management from the repo root so Cursor/Claude get the latest rules and methodology.
  3. Follow the methodology — If you went full install, work in order: 01 Concept of Operations → 02 Stakeholder Requirements → … → 05 Component Specs (one per bounded context), then 06–10 as needed. Each draft has a Methodology section that tells you how to fill it out.

The pack gives you document structure standards, requirement IDs and traceability (e.g. 02→03→05→08), and checklists for assessing and cleaning up existing docs. You can use it to "clean up messy docs" or to "establish from scratch"; the same install supports both.

Side-by-Side: Same Repo, Two Paths

| Full install | Review only | |--------------|-------------| | Creates docs/01-10 and draft templates | Does not create docs/01–10 or templates | | Best when you want the full methodology and are ready to map content into 01–10 | Best when you want to keep your current structure and improve it with checklists and standards | | Run ctx compile after install | Run ctx compile after install (optional but recommended) | | Use each draft's Methodology section to fill content | Use the pack's checklists (e.g. general document, metadata, traceability) on your existing docs |

Both paths give you the same rules, skills, and methodology in the repo; the only difference is whether the installer creates the standard doc folders and templates.

Example Repo and Where to Start

For a minimal "after" example you can clone or skim, we use a small test repo that shows the result of both install flavours (full and review-only). The structure and checklist content are documented in the pack's INSTALLATION and USAGE-GUIDES; the example repo is the same one we use to verify installs. [Add link to public example repo when published, e.g. GitHub URL.]

If you're cleaning up an existing repo, start with the "review only" install and the pack's checklists (general document, metadata, tools/assets, traceability, alignment). If you're starting a new project or want to adopt the full 01–10 layout, use the default (full) install and then work through the drafts in order.

Conclusion

You don't have to choose between "messy docs forever" and "big-bang restructure." The documentation management pack and CLI let you either improve in place with standards and checklists or adopt the full methodology and templates in one go. Install, run ctx compile, and then either follow the methodology in order or apply the checklists to what you already have. When you're ready to try it, get the pack or install the CLI and point it at your repo—and if you only want to tighten your current structure first, use the review-only option and add the full layout later.

[CTA: Get the pack / Try the CLI — add product or install link when publishing.]