Skip to content

Restructure the Build one guide - #43

Merged
jmchilton merged 4 commits into
mainfrom
agent/build-one-title-matrix
Aug 5, 2026
Merged

Restructure the Build one guide#43
jmchilton merged 4 commits into
mainfrom
agent/build-one-title-matrix

Conversation

@jmchilton

Copy link
Copy Markdown
Member

What changed

  • Rename the three Build one pages while keeping their existing URLs:
    • What a Foundry Needs
    • Plan Your Foundry
    • Build with the Astro Stack
  • Update the landing-page summaries and explicit cross-reference labels to match.
  • Move the first page’s orientation near the top as a five-row, three-column decision matrix: what stays consistent, what the domain decides, and evidence that the implementation is working.
  • Remove the later two-column recap so the page does not repeat the same orientation.
  • Rebuild Plan Your Foundry as an eight-phase vertical-slice roadmap.
  • Give every planning phase a consistent Goal / Produce / Done when structure.
  • Preserve the expanded glossary guidance as a deliberate deep dive rather than extracting it or flattening it to match the shorter phases.

Why

The Build one sequence had the right conceptual progression, but its titles blurred the distinction between planning and implementation. The planning page also promised a route to a working Foundry while presenting one developed glossary section surrounded by stubs.

This change makes the progression explicit:

  1. understand what a Foundry needs;
  2. plan the domain-specific implementation;
  3. build it with one concrete stack.

The glossary remains intentionally more detailed, while the repeated phase structure keeps the overall route scannable.

The larger validation-model question remains tracked separately in #41. This PR preserves the pattern’s current external-check position rather than resolving that issue implicitly.

Impact

Readers get clearer navigation, an earlier decision framework, and a complete stack-neutral planning path without breaking existing URLs.

Validation

  • npm test — 22 tests passed
  • npm run build — wiki-link check passed; 29 pages built and indexed
  • git diff --check

@jmchilton
jmchilton marked this pull request as ready for review August 5, 2026 10:53
@jmchilton
jmchilton merged commit d9b87f0 into main Aug 5, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant