docs: standardize documentation for get-bashed#8
Conversation
- Add CLAUDE.md (project-specific agent entry point, no global rule duplication) - Rewrite AGENTS.md (architecture detail, data flow, module table, CI/security surfaces) - Rewrite README.md (complete user-facing guide with all flags, profiles, features) - Add CHANGELOG.md (Keep a Changelog 1.1.0 from git history) - Add STANDARDS.md (non-negotiable code quality constraints) - Add docs/ARCHITECTURE.md (installer flow, runtime layer, tool registry, data flow) - Add docs/DESIGN.md (product vision, principles, UX goals, non-goals) - Add docs/TESTING.md (strategy, BATS setup, test files, CI coverage, how to add tests) - Add docs/STATE.md (what is done, in progress, next, known issues, active decisions) - Add YAML frontmatter to all root and docs/ .md files (title, updated, status, domain) - Add frontmatter to CONTRIBUTING.md, SECURITY.md, TOOLS.md, docs/CONFIG.md, docs/SHDOC.md, docs/README.md, docs/INDEX.md - Delete memory-bank/ (session dumps and Claude conversation artifacts) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 16 minutes and 16 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (23)
📝 WalkthroughWalkthroughThis PR replaces several memory-bank notes with a structured docs layout, adds new architecture/design/testing/standards/agent docs, rewrites README and AGENTS.md, adds CHANGELOG.md, inserts YAML front-matter into multiple docs, and tweaks docs generation to preserve frontmatter. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsTimed out fetching pipeline failures after 30000ms Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation Standardization Review
This PR successfully standardizes the project documentation with comprehensive, accurate content. All documentation accurately reflects the actual codebase implementation.
Verified:
- ✅ YAML frontmatter consistently applied across all documentation files
- ✅ Documentation content matches actual implementation in
install.sh,install.bash, and related files - ✅ All files meet the 300 LOC constraint
- ✅ Architecture, features, profiles, and tool registry accurately documented
- ✅ No functional code changes - documentation only
- ✅ Security guidance, testing approach, and CI/CD workflows properly documented
Summary:
This documentation overhaul significantly improves project clarity and maintainability. The new structure with CLAUDE.md, comprehensive AGENTS.md, detailed architecture docs, and standardized frontmatter provides excellent guidance for both users and contributors.
No blocking issues found. This PR is ready to merge once CI passes.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 22-42: The project layout fenced block in CLAUDE.md lacks a
language identifier (triggering MD040); update the opening triple-backtick for
the project layout code fence to include a language token (e.g., "text") so the
fence becomes ```text, leaving the fence content unchanged and preserving the
closing triple-backticks.
In `@docs/ARCHITECTURE.md`:
- Line 210: The doc claim that "All git clones use `--depth=1`" is inaccurate
because scripts/test-setup.sh performs full clones; either modify
scripts/test-setup.sh to add `--depth=1` to its git clone invocations for the
helper repos (identify and update the clone commands in scripts/test-setup.sh)
or relax the statement in docs/ARCHITECTURE.md to something like "Most git
clones use `--depth=1`; some setup scripts perform full clones" so the
documentation no longer asserts a false guarantee.
In `@docs/DESIGN.md`:
- Around line 48-49: The documentation line claiming "No auto-sourcing of secret
providers (Doppler, 1Password, etc.) happens at shell startup" is inaccurate
because Doppler is startup-sourced when explicitly enabled; update the sentence
in DESIGN.md to say secret providers are "not enabled by default" (or similar)
instead of "no auto-sourcing", and keep the note that secrets live in
~/.get-bashed/secrets.d/ and that explicit doppler_shell is provided for
on-demand injection so readers know Doppler can still be enabled explicitly.
In `@README.md`:
- Around line 76-77: Update the README entry for the doppler_env flag to
correctly state startup behavior: change the description from “does not
auto-source on startup” to something like “disabled by default; sourced on
startup only when explicitly enabled” and mention the activation via the
GET_BASHED_USE_DOPPLER=1 environment variable that causes the shell startup
script (99-secrets.sh) to source Doppler secrets; keep the bash_it entry
unchanged.
In `@STANDARDS.md`:
- Line 38: The file-size rule in STANDARDS.md enforces "Max 300 lines per file"
but conflicts with existing large scripts (e.g., installers/_helpers.sh); update
STANDARDS.md to scope the rule to new or modified files (or add an explicit
remediation plan and timeline) so it no longer contradicts the repo
state—specifically change the rule text to state it applies to new/modified
files or add a note with a remediation deadline and steps for refactoring
oversized scripts like installers/_helpers.sh.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ddd88fbb-334b-4a4f-b5e3-89c80b9b0e99
📒 Files selected for processing (22)
AGENTS.mdCHANGELOG.mdCLAUDE.mdCONTRIBUTING.mdREADME.mdSECURITY.mdSTANDARDS.mdTOOLS.mddocs/ARCHITECTURE.mddocs/CONFIG.mddocs/DESIGN.mddocs/INDEX.mddocs/README.mddocs/SHDOC.mddocs/STATE.mddocs/TESTING.mdmemory-bank/activeContext.mdmemory-bank/productContext.mdmemory-bank/progress.mdmemory-bank/projectbrief.mdmemory-bank/systemPatterns.mdmemory-bank/techContext.md
💤 Files with no reviewable changes (6)
- memory-bank/projectbrief.md
- memory-bank/techContext.md
- memory-bank/productContext.md
- memory-bank/activeContext.md
- memory-bank/progress.md
- memory-bank/systemPatterns.md
| ``` | ||
| bashrc # Interactive shell entrypoint | ||
| bash_profile # Login shell entrypoint (delegates to bashrc) | ||
| bash_aliases # Aliases sourced by bashrc | ||
| inputrc # Readline config | ||
| vimrc # Vim config | ||
| gitconfig # Git config template | ||
| bashrc.d/ # Ordered runtime modules (00- to 99-) | ||
| installers/ | ||
| tools.sh # Centralized tool registry | ||
| _helpers.sh # Platform helpers and tool handlers | ||
| profiles/ # Profile .env files (minimal, dev, ops) | ||
| bin/ # Portable helper scripts | ||
| scripts/ # CI, docs, and test helpers | ||
| tests/ # BATS test suite | ||
| docs/ # Generated and hand-authored docs | ||
| secrets.d/ # Local secrets (git-ignored) | ||
| install.sh # POSIX bootstrap (re-execs install.bash) | ||
| install.bash # Full installer, config writer, tool runner | ||
| Makefile # docs, lint, test | ||
| ``` |
There was a problem hiding this comment.
Add a language identifier to the project layout code fence.
Markdownlint MD040 is valid here: the fenced block starting at Line 22 should specify a language.
✏️ Proposed fix
-```
+```text
bashrc # Interactive shell entrypoint
bash_profile # Login shell entrypoint (delegates to bashrc)
bash_aliases # Aliases sourced by bashrc
@@
Makefile # docs, lint, test</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **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.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 22-22: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 22 - 42, The project layout fenced block in CLAUDE.md
lacks a language identifier (triggering MD040); update the opening
triple-backtick for the project layout code fence to include a language token
(e.g., "text") so the fence becomes ```text, leaving the fence content unchanged
and preserving the closing triple-backticks.
| - `install.sh` / `install.bash`: runs with user privileges. No sudo unless a package manager requires it. | ||
| - Tool installers: call system package managers (which may require sudo) or install to `~/.get-bashed/`. | ||
| - `secrets.d/`: sourced as shell code with user privileges. Content is never committed. | ||
| - All git clones use `--depth=1` to minimize exposure. |
There was a problem hiding this comment.
Absolute git clone --depth=1 claim is inaccurate.
Line 210 says all clones are shallow, but scripts/test-setup.sh clones helper repos without --depth=1. Please either update that script or relax this statement to avoid a false security guarantee.
Suggested wording change
-- All git clones use `--depth=1` to minimize exposure.
+- Git clones should prefer shallow clones where compatible; some helper-fetch flows may use full clones.📝 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.
| - All git clones use `--depth=1` to minimize exposure. | |
| - Git clones should prefer shallow clones where compatible; some helper-fetch flows may use full clones. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/ARCHITECTURE.md` at line 210, The doc claim that "All git clones use
`--depth=1`" is inaccurate because scripts/test-setup.sh performs full clones;
either modify scripts/test-setup.sh to add `--depth=1` to its git clone
invocations for the helper repos (identify and update the clone commands in
scripts/test-setup.sh) or relax the statement in docs/ARCHITECTURE.md to
something like "Most git clones use `--depth=1`; some setup scripts perform full
clones" so the documentation no longer asserts a false guarantee.
| Secrets belong in `~/.get-bashed/secrets.d/` which is git-ignored. No auto-sourcing of secret providers (Doppler, 1Password, etc.) happens at shell startup. Explicit `doppler_shell` is provided for on-demand injection. | ||
|
|
There was a problem hiding this comment.
Secret-provider startup claim conflicts with current runtime behavior.
This says secret providers are not auto-sourced at startup, but Doppler secrets are startup-sourced when Doppler is explicitly enabled. Please narrow wording to “not enabled by default” instead of “no auto-sourcing.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/DESIGN.md` around lines 48 - 49, The documentation line claiming "No
auto-sourcing of secret providers (Doppler, 1Password, etc.) happens at shell
startup" is inaccurate because Doppler is startup-sourced when explicitly
enabled; update the sentence in DESIGN.md to say secret providers are "not
enabled by default" (or similar) instead of "no auto-sourcing", and keep the
note that secrets live in ~/.get-bashed/secrets.d/ and that explicit
doppler_shell is provided for on-demand injection so readers know Doppler can
still be enabled explicitly.
| | `doppler_env` | Enable Doppler env integration (does not auto-source on startup) | | ||
| | `bash_it` | Enable the bash-it framework if installed | |
There was a problem hiding this comment.
Doppler startup behavior is documented incorrectly.
Line 76 says Doppler integration “does not auto-source on startup,” but bashrc.d/99-secrets.sh sources Doppler secrets during shell startup when GET_BASHED_USE_DOPPLER=1. Please reword to “disabled by default; sourced on startup only when explicitly enabled.”
Suggested doc fix
-| `doppler_env` | Enable Doppler env integration (does not auto-source on startup) |
+| `doppler_env` | Enable Doppler env integration (off by default; when enabled, secrets are sourced at shell startup) |📝 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.
| | `doppler_env` | Enable Doppler env integration (does not auto-source on startup) | | |
| | `bash_it` | Enable the bash-it framework if installed | | |
| | `doppler_env` | Enable Doppler env integration (off by default; when enabled, secrets are sourced at shell startup) | | |
| | `bash_it` | Enable the bash-it framework if installed | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 76 - 77, Update the README entry for the doppler_env
flag to correctly state startup behavior: change the description from “does not
auto-source on startup” to something like “disabled by default; sourced on
startup only when explicitly enabled” and mention the activation via the
GET_BASHED_USE_DOPPLER=1 environment variable that causes the shell startup
script (99-secrets.sh) to source Doppler secrets; keep the bash_it entry
unchanged.
|
|
||
| ## File Size | ||
|
|
||
| - Max 300 lines per file. Scripts that grow beyond this must be decomposed. |
There was a problem hiding this comment.
File-size rule is currently contradicted by the repo state.
This sets a strict 300-line cap, but existing installers/_helpers.sh is already much larger. Consider scoping this as a forward-looking rule (new/modified files) or adding an explicit remediation plan/timeline.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@STANDARDS.md` at line 38, The file-size rule in STANDARDS.md enforces "Max
300 lines per file" but conflicts with existing large scripts (e.g.,
installers/_helpers.sh); update STANDARDS.md to scope the rule to new or
modified files (or add an explicit remediation plan and timeline) so it no
longer contradicts the repo state—specifically change the rule text to state it
applies to new/modified files or add a note with a remediation deadline and
steps for refactoring oversized scripts like installers/_helpers.sh.
There was a problem hiding this comment.
Pull request overview
This PR standardizes the get-bashed documentation set by rewriting/adding core docs, introducing consistent YAML frontmatter across root and docs/ markdown files, and removing the legacy memory-bank/ session artifacts.
Changes:
- Added/reworked project documentation (README, standards, architecture/design/testing/state, changelog, agent guidance).
- Added YAML frontmatter (
title,updated,status,domain) to root anddocs/markdown files. - Deleted
memory-bank/docs in favor of the new canonical documentation set.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
TOOLS.md |
Adds YAML frontmatter to the tools/language management doc. |
STANDARDS.md |
Introduces “non-negotiable” repo standards and constraints. |
SECURITY.md |
Adds YAML frontmatter to the security policy doc. |
README.md |
Rewrites the user guide (profiles/features/tools/options) and adds frontmatter. |
CHANGELOG.md |
Adds a Keep a Changelog–style changelog with initial release notes and frontmatter. |
CLAUDE.md |
Adds an agent entry point with repo layout and common commands. |
AGENTS.md |
Rewrites extended agent guidance (architecture, workflows, security surfaces) + frontmatter. |
docs/ARCHITECTURE.md |
Adds a detailed installer/runtime architecture and data-flow doc. |
docs/DESIGN.md |
Adds product design principles, UX goals, and non-goals. |
docs/TESTING.md |
Adds testing strategy and CI/linting guidance for BATS and pre-commit. |
docs/STATE.md |
Adds a consolidated project state/status doc replacing memory-bank context files. |
docs/SHDOC.md |
Adds YAML frontmatter to shdoc documentation. |
docs/README.md |
Adds YAML frontmatter to the docs pipeline overview. |
docs/INDEX.md |
Adds YAML frontmatter to the docs index. |
docs/CONFIG.md |
Adds YAML frontmatter to configuration docs. |
memory-bank/techContext.md |
Deleted (legacy memory-bank artifact). |
memory-bank/systemPatterns.md |
Deleted (legacy memory-bank artifact). |
memory-bank/projectbrief.md |
Deleted (legacy memory-bank artifact). |
memory-bank/progress.md |
Deleted (legacy memory-bank artifact). |
memory-bank/productContext.md |
Deleted (legacy memory-bank artifact). |
memory-bank/activeContext.md |
Deleted (legacy memory-bank artifact). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## File Size | ||
|
|
||
| - Max 300 lines per file. Scripts that grow beyond this must be decomposed. | ||
|
|
| - All git clones use `--depth=1` to minimize exposure. | ||
| - All curl downloads use `-fsSL` (fail on error, silent, follow redirects) with no verification bypass. |
| - `bashate` — PEP 8 style for shell (max line length 120). | ||
| - `actionlint` — GitHub Actions workflow linting. | ||
| - `gitleaks` — secret detection. | ||
| - Standard file hygiene (trailing whitespace, end-of-file newlines, YAML/JSON validation). |
| - `66-doppler.sh`: Doppler env init (conditional). | ||
| - `70-bash-it.sh`: bash-it activation (conditional). | ||
| - `70-env.sh`: general env vars. | ||
| - `80-aliases.sh`: alias definitions. | ||
| - `90-functions.sh`: utility functions (`ex` extractor, `doppler_shell`, `get_bashed_component`). |
| - `--with-ui` flag for curses `dialog` interactive setup. | ||
| - `--dry-run`, `--list`, `--list-profiles`, `--list-features`, `--list-installers` discovery flags. | ||
| - `--auto` / `--yes` flags for non-interactive installs. | ||
| - `get_bashed_component` helper for enabling bash-it components or falling back to asdf/brew/system installs. |
| ## Quick start | ||
|
|
||
| ```bash | ||
| curl -fsSL -o install.sh https://raw.githubusercontent.com/jbcom/get-bashed/main/install.sh | ||
| # Review install.sh before running | ||
| sh install.sh | ||
| ``` |
|
|
||
| | Flag | Description | | ||
| |---|---| | ||
| | `--prefix PATH` | Install to PATH instead of `~/.get-bashed` | |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request replaces the project's "Memory Bank" documentation system with a comprehensive suite of standardized files, including CLAUDE.md, AGENTS.md, and STANDARDS.md, alongside detailed technical guides in the docs/ directory. These changes formalize the project's architecture, design principles, and testing strategies while adding a versioned changelog and an expanded README. Review feedback identifies a recurring inconsistency across the new documentation regarding Doppler integration, which is incorrectly attributed to a standalone module instead of the secrets module where the logic is actually implemented.
| | `50-` | Tool init (starship, direnv, cargo) | | ||
| | `60-` | asdf version manager activation | | ||
| | `65-` | Optional CLI tools | | ||
| | `66-` | Doppler env integration | |
There was a problem hiding this comment.
The documentation indicates that Doppler environment integration is handled by 66-doppler.sh. However, the implementation in bashrc.d/99-secrets.sh (lines 12-16) already contains the logic to source Doppler secrets. This discrepancy could lead to redundant sourcing or confusion if 66-doppler.sh does not exist or performs the same task.
| - `50-tool-init.sh`: Cargo env, starship, direnv init. | ||
| - `60-asdf.sh`: asdf activation. | ||
| - `65-tools.sh`: optional CLI tool auto-install. | ||
| - `66-doppler.sh`: Doppler env init (conditional). |
There was a problem hiding this comment.
The state documentation lists 66-doppler.sh as the module for Doppler env initialization. This is inconsistent with the provided code in bashrc.d/99-secrets.sh which handles this responsibility. The documentation should be updated to match the codebase structure.
Summary
CLAUDE.md,AGENTS.md(rewrite),README.md(rewrite),CHANGELOG.md,STANDARDS.md,docs/ARCHITECTURE.md,docs/DESIGN.md,docs/TESTING.md,docs/STATE.mdtitle,updated,status,domain) to all root anddocs/markdown filesmemory-bank/directory (session dumps, Claude conversation artifacts, WET duplicates of information now in proper docs)CLAUDE.md, content is accurate to the actual codebaseFiles changed
CLAUDE.mdAGENTS.mdREADME.mdCHANGELOG.mdSTANDARDS.mddocs/ARCHITECTURE.mddocs/DESIGN.mddocs/TESTING.mddocs/STATE.mdCONTRIBUTING.md,SECURITY.md,TOOLS.md,docs/CONFIG.md,docs/SHDOC.md,docs/README.md,docs/INDEX.mdmemory-bank/Test plan
.mdfiles in root anddocs/have YAML frontmatter🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation