Skip to content

Clarify woostack guides and align documentation with current workflows - #710

Merged
howarewoo merged 1 commit into
mainfrom
adam/clarify-woostack-documentation
Sep 8, 2026
Merged

howarewoo merged 1 commit into
mainfrom
adam/clarify-woostack-documentation

Conversation

@howarewoo

@howarewoo howarewoo commented Sep 7, 2026

Copy link
Copy Markdown
Owner

Summary

  • Rewrite all 27 authored documentation pages and the reader-facing guides for entry- to mid-level programmers.
  • Explain workflow terminology and remove repetitive or inflated prose while preserving safety boundaries.
  • Correct setup prerequisites, configuration examples, branch precedence, review-angle behavior, deployment notes, and stale Build/revision/provider guidance.
  • Remove tests that pin documentation wording or parser identity; retain generator behavior coverage.

Affected spec sections

  • spec/architecture.md
  • spec/frameworks.md
  • spec/infrastructure.md
  • spec/patterns.md
  • spec/development.md
  • spec/bootstrap.md
  • README.md / other top-level docs
  • Authored site guides, benchmark guide, and affected skill references

Notes for downstream projects

No runtime code changes. The configuration guide now documents two implementation gaps: Review can reject configuration without a review object, and Audit detection does not always enforce the security coverage required by its skill.

Checklist

  • Cross-links to related sections still resolve
  • No version numbers hard-coded in frameworks.md where "latest" suffices

Goal

Make woostack documentation accurate and understandable for entry- to mid-level programmers.

Test plan

Automated

  • pnpm -C site build: passed; 24 skill pages regenerated and 159 static pages generated. Build reported middleware deprecation and missing metadataBase warnings.
  • pnpm -C site test: passed, 11 generator tests.
  • In-memory documentation checks: 220 local links and heading anchors resolved; all 10 JSON examples parsed.

Manual

  • Compared documentation claims with the owning skills, configuration loaders, host adapters, and generation scripts.
  • Browser visual inspection, live provider workflows, and the remote benchmark were not run; this change updates prose and references.

- Explain setup, planning, review, providers, and harness behavior in
  plain language while preserving approval and merge boundaries.
- Correct stale configuration, branching, and retained-run guidance.
- Remove tests that pin documentation wording and parser identity.

Copy link
Copy Markdown
Owner Author

This stack of pull requests is managed by Graphite. Learn more about stacking.

@howarewoo
howarewoo marked this pull request as ready for review September 8, 2026 14:53
@howarewoo
howarewoo merged commit 1d556d8 into main Sep 8, 2026
@howarewoo
howarewoo deleted the adam/clarify-woostack-documentation branch September 8, 2026 14:53
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