From 1a4dffbc866743e86c301aee5fb7025076c1fe66 Mon Sep 17 00:00:00 2001 From: Anthony Johnson II Date: Thu, 18 Jun 2026 14:53:42 -0700 Subject: [PATCH] docs(workspace): organize project docs --- .github/CODEOWNERS | 15 +++++++++++++++ CHANGELOG.md | 3 +++ CONTRIBUTING.md | 2 +- README.md | 4 +++- app_docs/README.md | 6 +++++- app_docs/reports/README.md | 13 +++++++++++++ FAQ.md => docs/FAQ.md | 0 docs/README.md | 14 ++++++++++++++ RELEASE_CHECKLIST.md => docs/RELEASE_CHECKLIST.md | 2 +- 9 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 app_docs/reports/README.md rename FAQ.md => docs/FAQ.md (100%) create mode 100644 docs/README.md rename RELEASE_CHECKLIST.md => docs/RELEASE_CHECKLIST.md (98%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..bc7a6aa --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,15 @@ +# Review ownership for framework-critical paths. +* @AJ-EthereaLogic-ai + +/.claude/ @AJ-EthereaLogic-ai +/tests/ @AJ-EthereaLogic-ai +/docs/ @AJ-EthereaLogic-ai +/app_docs/ @AJ-EthereaLogic-ai +/specs/docs/ @AJ-EthereaLogic-ai +/spec_driven_docs/ @AJ-EthereaLogic-ai + +/AGENTS.md @AJ-EthereaLogic-ai +/CLAUDE.md @AJ-EthereaLogic-ai +/CONSTITUTION.md @AJ-EthereaLogic-ai +/DIRECTIVES.md @AJ-EthereaLogic-ai +/.github/workflows/ @AJ-EthereaLogic-ai diff --git a/CHANGELOG.md b/CHANGELOG.md index 0da929f..716968d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -119,6 +119,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Docs: moved the FAQ and release checklist into `docs/`, added a project docs + index, added a reports index under `app_docs/reports/`, and added + `.github/CODEOWNERS` for maintainer review routing. - Codacy: bumped `.codacy/codacy.yaml` to current CLI tooling — dropped the `java` runtime and `pmd`/`semgrep`, added `opengrep`, and bumped `lizard`/`pylint`/`trivy` versions (PR \#29) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe6134f..4df4d15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,7 @@ npm run lint:md This project follows [Semantic Versioning 2.0.0](https://semver.org/). For the full versioning policy, deprecation rules, runtime compatibility matrix, and the -mandatory pre-release checklist, see [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md). +mandatory pre-release checklist, see [RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). ## Commit style diff --git a/README.md b/README.md index 4ade0e6..4b5b49d 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ promotion into `pending_approval/`. | Document | Purpose | |----------|---------| | [User Guide](app_docs/User-Guide/User-Guide.md) | Comprehensive guide to all features | -| [FAQ](FAQ.md) | Common questions about setup, workflow, and quality gates | +| [FAQ](docs/FAQ.md) | Common questions about setup, workflow, and quality gates | | [Contributing](CONTRIBUTING.md) | Contribution workflow, standards, and quality expectations | ### Related documentation @@ -261,6 +261,7 @@ Utility agents handle development hygiene and prompt engineering tasks. ```text . ├── .claude/ # Commands, agents, hooks, templates, and quality rules +├── docs/ # Project FAQ and release documentation ├── specs/docs/ # Input specifications ├── spec_driven_docs/ # Generated output by workflow stage │ ├── rough_draft/ @@ -268,6 +269,7 @@ Utility agents handle development hygiene and prompt engineering tasks. │ └── approved_final/ ├── app_docs/ # End-user documentation │ └── User-Guide/ # Framework user guide +├── app_docs/reports/ # Tracked audit and readiness reports ├── prompt/ # Prompt engineering resources └── README.md # This file ``` diff --git a/app_docs/README.md b/app_docs/README.md index da94291..d12ca66 100644 --- a/app_docs/README.md +++ b/app_docs/README.md @@ -14,7 +14,7 @@ This directory contains documentation for **users** of the Spec-Driven Docs Syst - **Tutorials:** Step-by-step tutorials for common workflows - **Command reference:** Detailed reference for all slash commands - **Examples:** Real-world examples and recipes -- **FAQ:** Frequently asked questions and troubleshooting +- **End-user FAQs:** Questions specific to using the framework ## What Does NOT Belong Here @@ -27,6 +27,10 @@ This directory contains documentation for **users** of the Spec-Driven Docs Syst - [User Guide](User-Guide/User-Guide.md) - Comprehensive guide to all framework features +## Related Documentation + +- [Project FAQ](../docs/FAQ.md) - Common setup, workflow, and quality-gate questions + ## Contributing When adding end-user documentation: diff --git a/app_docs/reports/README.md b/app_docs/reports/README.md new file mode 100644 index 0000000..3e5cd16 --- /dev/null +++ b/app_docs/reports/README.md @@ -0,0 +1,13 @@ +# Reports + +This directory contains tracked review, audit, and release-readiness reports. + +Treat these files as historical evidence for the repository state named in each report. + +## Current Reports + +- [Code scanning analysis](CODE_SCANNING_ANALYSIS.md) +- [End-to-end test report](E2E_TEST_REPORT.md) +- [End-to-end test report - 2026-04-26](E2E_TEST_REPORT_2026_04_26.md) +- [Improvement opportunities](IMPROVEMENT_OPPORTUNITIES.md) +- [Release readiness audit - 2026-04-26](RELEASE_READINESS_AUDIT_2026-04-26.md) diff --git a/FAQ.md b/docs/FAQ.md similarity index 100% rename from FAQ.md rename to docs/FAQ.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..990edc1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Project Documentation + +This directory contains project-facing documentation for contributors, maintainers, and release operators. + +## Current Documents + +- [FAQ](FAQ.md) +- [Release Checklist](RELEASE_CHECKLIST.md) + +## Related Documentation + +- End-user guide: [app_docs/User-Guide/User-Guide.md](../app_docs/User-Guide/User-Guide.md) +- Specification inputs: [specs/docs/README.md](../specs/docs/README.md) +- Workflow output stages: [spec_driven_docs/README.md](../spec_driven_docs/README.md) diff --git a/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md similarity index 98% rename from RELEASE_CHECKLIST.md rename to docs/RELEASE_CHECKLIST.md index 05735e8..7711677 100644 --- a/RELEASE_CHECKLIST.md +++ b/docs/RELEASE_CHECKLIST.md @@ -22,7 +22,7 @@ verified, and obtain a second-maintainer sign-off before tagging. - [ ] `CHANGELOG.md` — new release section added above `[Unreleased]`, entries accurate and complete -- [ ] Public-facing docs (`README.md`, `FAQ.md`, User Guide, command docs under +- [ ] Public-facing docs (`README.md`, `docs/FAQ.md`, User Guide, command docs under `.claude/commands/doc/`) reflect any changed behavior - [ ] New or changed commands have updated help text - [ ] New agent definitions in `.claude/agents/` include `description`, `model`,