Initial commit

shavakan/docs-readme.md

@@ -0,0 +1,156 @@
+---
+description: Generate/update condensed developer README for project usage and contribution
+---
+
+# README Generator
+
+Create/update README.md in project root. **Constraints: < 200 lines, scannable in 30 seconds, technical tone (no marketing).**
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Analysis Phase
+
+Check files in order, record findings:
+
+1. `flake.nix` → Nix flake present (Y/N)
+2. `.envrc` + `.envrc.example` → direnv present (Y/N)
+3. `Makefile` → Make targets available (Y/N)
+4. `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → Language ecosystem
+5. Existing `README.md` → Preserve badges, screenshots, custom sections
+6. Entry points → `main.py`, `index.ts`, `cmd/main.go`, etc
+
+## Build System Priority
+
+**Select primary build interface based on presence:**
+
+| Priority | System | When | Commands |
+|----------|--------|------|----------|
+| 1 | Nix | `flake.nix` exists | `nix develop`, `nix build`, `nix run` |
+| 2 | Make | `Makefile` exists | `make install`, `make test`, `make build` |
+| 3 | Package manager | `package.json` / `Cargo.toml` | `npm install`, `cargo build` |
+| 4 | Direct | None above | `python -m`, `go run`, etc |
+
+**If multiple exist**: Use highest priority as primary, mention others as alternatives.
+
+## Environment Management
+
+**If `.envrc` exists:**
+- Prerequisites: Add "direnv" requirement
+- Install step: Add `cp .envrc.example .envrc && direnv allow`
+- Configuration section: Reference `.envrc.example` for variables
+
+**If no direnv**:
+- Use `.env` files or manual `export` commands
+- Configuration section: List env vars inline
+
+## README Composition
+
+**Required sections (generate in order):**
+
+### 1. Title + Summary
+```
+# [Project Name]
+> [Single sentence: does X for Y users]
+```
+
+### 2. Quick Start
+
+**Prerequisites**: List tools with versions. Omit language version if Nix manages it. Include Nix/direnv if detected.
+
+**Install**: Commands to get dependencies. Prioritize by build system table above.
+
+**Run**: Command to start/execute. Include port/URL for web apps.
+
+**Test**: Command to run tests. Use `nix flake check` if available.
+
+### 3. Project Structure
+
+Tree diagram of key directories with inline comments:
+```
+src/
+  core/       # Business logic
+  api/        # Endpoints
+tests/        # Test suite
+```
+
+### 4. Development
+
+**Setup**: Additional dev steps (direnv, pre-commit hooks, etc)
+
+**Build/Lint/Format**: Commands using primary build system
+
+**Common tasks**: 2-3 bullet points for frequent operations
+
+### 5. Optional Sections (include only if applicable)
+
+**Architecture**: 2-3 sentences on design decisions and tradeoffs. Include if non-obvious.
+
+**Configuration**: Env vars with descriptions. Required vs optional. Include if app needs config.
+
+**Deployment**: Deploy command or link. Include for deployable apps.
+
+**Contributing**: Link to CONTRIBUTING.md or inline if < 5 rules.
+
+**License**: License type. Include if LICENSE file exists.
+
+## Output Format Rules
+
+**Command syntax:**
+- Multi-word commands: Always use code blocks, never inline
+- Good: "Run:\n```bash\nnpm run dev\n```"
+- Bad: "Run `npm run dev`"
+
+**Section length**: Each section < 15 lines. Link to detailed docs if longer.
+
+**Style**: Technical, direct. Explain WHY for architecture, not WHAT code does. No "easy", "simple", "just".
+
+**Preservation**: Keep existing badges, screenshots, unique sections from old README.
+
+## Project Type Adaptations
+
+| Type | Adaptations |
+|------|-------------|
+| CLI tool | Add "Usage" with examples, omit "Running" |
+| Library | Add "Installation" + "Usage" with API examples, omit "Running" |
+| Web app | Include PORT/URL in "Run", add "Deployment" |
+| Monorepo | Show workspace structure, document per-package commands |
+| Nix multi-output | Add `nix flake show` output, document available apps/packages |
+
+## Execution Workflow
+
+1. Run analysis phase → Collect build system, env management, project type
+2. Generate README content using composition rules
+3. Show preview with summary: "[Project type] with [build system]. README uses [commands]. ~[N] lines."
+4. **If approved** → Write to `README.md`
+5. **If rejected** → Ask what to change, regenerate from step 2
+
+## Edge Cases
+
+**No build system found**: Use direct language commands (python, go run, etc) and warn in preview.
+
+**Nix without devShell**: Use `nix-shell` or `nix develop` with warnings about flake completeness.
+
+**Multiple entry points**: List all in "Run" section with descriptions.
+
+**Secrets in .envrc**: Never read actual `.envrc`, only `.envrc.example`. Remind about `.gitignore`.
+
+## Example Execution
+
+**Input**: "Generate README"
+
+**Analysis**:
+- flake.nix: Yes (Nix development shell + app)
+- .envrc: Yes (with .envrc.example)
+- Makefile: Yes (install/test/build targets)
+- package.json: Yes (Next.js)
+- Entry: pages/index.tsx
+
+**Build priority**: Nix (priority 1), mention Make as fallback
+
+**Preview**: "Next.js web app with Nix flake and direnv. README uses `nix run` for primary interface, notes `make` commands as alternative. Includes .envrc.example setup. ~90 lines. Approve?"
+
+**Output**: README.md with Nix-first commands, direnv setup, project structure showing pages/ and components/, development section with `nix build` and `nix flake check`.