Skip to content

docs: refresh README discovery - #5

Merged
Faeif merged 1 commit into
mainfrom
codex/readme-discovery
Aug 11, 2026
Merged

docs: refresh README discovery#5
Faeif merged 1 commit into
mainfrom
codex/readme-discovery

Conversation

@Faeif

@Faeif Faeif commented Aug 11, 2026

Copy link
Copy Markdown
Owner

What changed

  • Added a polished editorial cover image and clear project identity.
  • Reworked the README around value, five-minute setup, workflow, and team use.
  • Restored the complete, expandable list of all 13 skills for prospective users and forkers.

Why

Make CaseKit easier to discover, understand, and adopt from its GitHub landing page.

Validation

  • python3 scripts/validate_suite.py

@Faeif
Faeif marked this pull request as ready for review August 11, 2026 20:07
@Faeif
Faeif merged commit 373de50 into main Aug 11, 2026
3 of 4 checks passed

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Devin Review found 2 potential issues.

Open in Devin Review

Comment thread README.md
Comment on lines +41 to +45
cd casekit
python3 install.py --scope project --project-root /path/to/your-case
python3 casekit.py init /path/to/your-case --layout clean --team "Alice,Bob,Carol"
```

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔴 The five-minute getting-started instructions fail because the second command refuses to run

The quick-start tells new users to install into the case folder first (python3 install.py --scope project --project-root /path/to/your-case at README.md:42), which creates that folder before the workspace-creation command runs, so the next command aborts with "Refusing to overwrite existing path" and no workspace is ever created.
Impact: Anyone following the headline setup instructions hits an error and cannot create a case workspace.

Why the ordering breaks: init refuses pre-existing destinations and already installs skills itself

cmd_init in casekit.py:170-173 raises SystemExit(f"Refusing to overwrite existing path: {destination}") when the destination exists. install.py --scope project --project-root /path/to/your-case creates /path/to/your-case/.agents and /path/to/your-case/.claude, so the directory exists by the time casekit.py init runs. Reproduced locally: the second command prints Refusing to overwrite existing path.

Additionally the install step is redundant: casekit.py:180 already runs install.py --scope project --project-root <destination> as part of init.

Suggested change
cd casekit
python3 install.py --scope project --project-root /path/to/your-case
python3 casekit.py init /path/to/your-case --layout clean --team "Alice,Bob,Carol"
```
cd casekit
python3 casekit.py init /path/to/your-case --layout clean --team "Alice,Bob,Carol"

<!-- devin-review-badge-begin -->
<a href="https://app.devin.ai/review/faeif/casekit/pull/5" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
    <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open in Devin Review">
  </picture>
</a>
<!-- devin-review-badge-end -->

---
*Was this helpful? React with 👍 or 👎 to provide feedback.*

Comment thread README.md
4. An Integrator promotes approved work into `03-OFFICIAL/` and the final deck.
5. Run validation before every PR, rehearsal, and submission.

This keeps exploration safe: chat output and unconfirmed ideas stay in personal drafts; only a decision or test turns an idea into an official artifact. Generated workspaces include `README-START-HERE.md` and `TEAM-WORKFLOW.md` with the exact workflow.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Team setup section names starting files that do not exist in the team layout

The team-workflow section says generated workspaces include README-START-HERE.md and TEAM-WORKFLOW.md (README.md:126), but for the team layout described in that section those two files are deleted and replaced by a single 00-START-HERE.md, so teams look for onboarding files that are not there.
Impact: New teams following the documented team setup cannot find the starting instructions the README points them to.

Clean layout removes both files

apply_clean_layout in casekit.py:135-139 unlinks README-START-HERE.md and TEAM-WORKFLOW.md, then writes clean-layout docs; casekit.py:196 prints 00-START-HERE.md as the starting point for --layout clean, and scripts/validate_suite.py:157-158 asserts 00-START-HERE.md exists in the clean layout.

Suggested change
This keeps exploration safe: chat output and unconfirmed ideas stay in personal drafts; only a decision or test turns an idea into an official artifact. Generated workspaces include `README-START-HERE.md` and `TEAM-WORKFLOW.md` with the exact workflow.
This keeps exploration safe: chat output and unconfirmed ideas stay in personal drafts; only a decision or test turns an idea into an official artifact. Team workspaces created with `--layout clean` include `00-START-HERE.md` with the exact workflow.
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

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