Skip to content

[codex] Organize project docs #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Anthony Johnson II (AJ-EthereaLogic-ai) merged 1 commit into from
Jun 18, 2026
Merged

[codex] Organize project docs #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -261,13 +261,15 @@ 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/
│ ├── pending_approval/
│ └── 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
```
Expand Down
6 changes: 5 additions & 1 deletion app_docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand Down
13 changes: 13 additions & 0 deletions app_docs/reports/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix heading capitalization to use sentence-case.

Heading on line 7 uses title-case instead of sentence-case. "Current Reports" should be "Current reports" per coding guidelines.

🔧 Proposed fix 
-## Current Reports
+## Current reports
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Current Reports
## Current reports
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app_docs/reports/README.md` at line 7, The heading "Current Reports" on line
7 in the README.md file uses title-case capitalization but should use
sentence-case per coding guidelines. Change the heading from "## Current
Reports" to "## Current reports" by converting the second word to lowercase
while keeping the first word capitalized.

Source: Coding guidelines


- [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)
0 FAQ.md → docs/FAQ.md
View file
Open in desktop
File renamed without changes.
14 changes: 14 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Project Documentation

@coderabbitai coderabbitai Bot Jun 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix heading capitalization to use sentence-case.

Headings on lines 1, 5, and 10 use title-case instead of sentence-case. As per coding guidelines, Markdown headings should use sentence-case (capitalize only the first letter and proper nouns).

  • Line 1: "Project Documentation" → "Project documentation"
  • Line 5: "Current Documents" → "Current documents"
  • Line 10: "Related Documentation" → "Related documentation"
🔧 Proposed fix 
-# Project Documentation
+# Project documentation

-## Current Documents
+## Current documents

-## Related Documentation
+## Related documentation

Also applies to: 5-5, 10-10

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/README.md` at line 1, The Markdown headings in the file use title-case
capitalization instead of sentence-case as required by the coding guidelines.
Change the following headings to use sentence-case (capitalize only the first
letter and proper nouns): "Project Documentation" to "Project documentation",
"Current Documents" to "Current documents", and "Related Documentation" to
"Related documentation". Review all headings in the document to ensure they
follow this sentence-case convention.

Source: Coding guidelines


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)
2 changes: 1 addition & 1 deletion RELEASE_CHECKLIST.md → docs/RELEASE_CHECKLIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
Loading