diff --git a/README.md b/README.md index b5ad50e..4b1b923 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Point Claude at a repository and let Lazarus help make it: Alive again, document - πŸ”§ **Make it run** (`discover` β†’ `repair`) β€” point it at code that won't start, or that you simply don't know yet. It investigates, proposes a plan with a concrete "done" checklist you approve, then works through the blockers until the app boots β€” and writes down what actually worked so the next person (or the next you) doesn't start from zero. - 🧭 **Assess it β€” and, if you choose, fix it** (`audit` β†’ `audit-repair`) β€” get a principal-engineer read: what's risky, what to fix first, and whether to maintain, refactor, or rewrite. A report you act on, hand to a client β€” or have executed finding-by-finding, each behind your approval. -- πŸ’… **Make it presentable β€” and, if you choose, fix that too** (`presentation` β†’ `presentation-repair`) β€” a DevRel-grade, read-only review of everything a stranger sees *before* the source: README, LICENSE, CONTRIBUTING, security policy, templates, markdown accessibility. Every finding cites a real standard (GitHub's community profile, CommonMark, WCAG) β€” never taste. Then `presentation-repair` executes the findings you ratify, asking for the facts only you own (which license? what security contact?) instead of inventing them. +- πŸ’… **Polish your repo's public page β€” and, if you choose, fix it too** (`presentation` β†’ `presentation-repair`) β€” not the code: the **README and the files around it** (LICENSE, CONTRIBUTING, security policy, issue templates, markdown accessibility) β€” everything a visitor sees on your GitHub page *before* reading the source. Every finding cites a real standard (GitHub's community profile, CommonMark, WCAG) β€” never taste. Then `presentation-repair` executes the findings you ratify, asking for the facts only you own (which license? what security contact?) instead of inventing them. Everything runs behind a guard that blocks destructive commands before they ever run β€” and **nothing changes until you approve a plan.** It'll resurrect a dead repo that won't even start (the namesake), but it's just as useful on healthy code you want made runnable, understood, assessed, or ready to show the world. @@ -35,7 +35,7 @@ Lazarus looks like six skills, but you only ever choose a **goal**. Each flows * |---|---|---| | **It running** β€” *"it won't start"* Β· *"I'm lost in this repo"* Β· *"I need to change it safely"* | πŸ” **`discover`** β†’ πŸ§‘ *you approve* β†’ πŸ”§ **`repair`** | `discover` investigates read-only and writes a plan with a runnable "done" checklist; you approve it; `repair` works the blockers until each one passes β€” recording what actually worked in `CLAUDE.md`. | | **It assessed β€” and, if you choose, fixed** β€” *"what shape is this in?"* Β· *"maintain, refactor, or rewrite?"* Β· *"now go fix what the audit found"* | 🧭 **`audit`** β†’ πŸ§‘ *your call* β†’ πŸ› οΈ **`audit-repair`** | `audit` writes a read-only, 12-section principal-engineer report. Stop there β€” it's a deliverable you can hand to a client β€” or ratify its Top 10 and `audit-repair` executes them **one at a time**, verifying each against its acceptance check. | -| **It presentable β€” and, if you choose, fixed** β€” *"polish my README"* Β· *"is this repo ready to go public?"* Β· *"set up CONTRIBUTING / templates"* | πŸ’… **`presentation`** β†’ πŸ§‘ *your call* β†’ 🧰 **`presentation-repair`** | `presentation` writes a read-only, project-type-aware audit β€” every finding citing a named standard, with a waiver file so it never nags you about deliberate choices. Stop there, or ratify the findings and `presentation-repair` executes them one at a time β€” re-checking each before editing, asking for facts only you own (license, security contact) instead of inventing them, and running **zero commands** the whole time. | +| **Your repo page presentable** (the README + community files) **β€” and, if you choose, fixed** β€” *"polish my README"* Β· *"is this repo ready to go public?"* Β· *"set up CONTRIBUTING / templates"* | πŸ’… **`presentation`** β†’ πŸ§‘ *your call* β†’ 🧰 **`presentation-repair`** | `presentation` writes a read-only, project-type-aware audit β€” every finding citing a named standard, with a waiver file so it never nags you about deliberate choices. Stop there, or ratify the findings and `presentation-repair` executes them one at a time β€” re-checking each before editing, asking for facts only you own (license, security contact) instead of inventing them, and running **zero commands** the whole time. | And the whole time β€” every journey, every step β€” the πŸ›‘οΈ **guard** blocks `rm -rf /`, force-push, `DROP TABLE`, and ~25 more destructive commands before they ever execute. @@ -101,7 +101,7 @@ flowchart LR J --> K["πŸ› οΈ lazarus:audit-repair
one finding at a time"] K --> L["βœ… findings fixed +
verified against checks"] - B -->|make it presentable| M["πŸ’… lazarus:presentation
read-only"] + B -->|polish the repo page| M["πŸ’… lazarus:presentation
read-only"] M --> N["πŸ“ PRESENTATION_AUDIT.md
scorecard Β· cited findings
Β· recommended fixes"] N -.->|"optional"| O(["πŸ§‘ you ratify
the findings"]) O --> P["🧰 lazarus:presentation-repair
one finding at a time, zero shell"] @@ -134,7 +134,7 @@ flowchart LR | **`/lazarus:audit`** | *"review this code"* Β· *"audit this repo"* Β· *"what should we fix first?"* Β· *"refactor or rewrite?"* | Produces a 12-section `CODEBASE_AUDIT.md` β€” architecture, risks, security, frontend/accessibility, a phased plan. **Read-only**; feeds `audit-repair` if you choose to act on it. | | **`/lazarus:audit-repair`** | *"execute the audit"* Β· *"fix the audit findings"* Β· *"work the Top 10 action items"* Β· *"apply the modernization plan"* | Executes a ratified `CODEBASE_AUDIT.md` Β§11 **one finding at a time** β€” ratify β†’ act β†’ verify against each item's acceptance check β€” safety-rails first, behind the guard. The strategic apply phase, exactly as `repair` is for `discover`. | -**Journey 3 β€” make it presentable, then (optionally) fix it** +**Journey 3 β€” polish the repo page (README + community files), then (optionally) fix it** | Command | Also triggers on… | What it does | |---|---|---| diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index c801f3b..9965242 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -26,7 +26,7 @@ Lazarus works on *any* repo: one you inherited, an open-source project, your own - **πŸ”§ Make it run.** Point it at code that won't start (or that you just don't know yet). It investigates, proposes a plan with a concrete "done" checklist you approve, then works through the blockers until the app boots β€” and writes down what actually worked so the next person doesn't start from zero. - **🧭 Assess it β€” and, if you choose, fix it.** Get a principal-engineer read: what's risky, what to fix first, and whether to maintain, refactor, or rewrite. A report you act on, hand to a client β€” or have executed finding-by-finding by `audit-repair`, each behind your approval. The audit itself changes nothing. -- **πŸ’… Make it presentable β€” and, if you choose, fix that too.** A DevRel-grade, read-only review of everything a stranger sees before the source β€” README, community-health files, markdown accessibility β€” graded against cited standards, never taste. Produces `PRESENTATION_AUDIT.md`; then `presentation-repair` executes the findings you ratify, asking for the facts only you own instead of inventing them. +- **πŸ’… Polish the repo's public page β€” and, if you choose, fix it too.** Not the code: the README and the files around it β€” community-health files, markdown accessibility β€” everything a visitor sees on the GitHub page before the source, graded against cited standards, never taste. Produces `PRESENTATION_AUDIT.md`; then `presentation-repair` executes the findings you ratify, asking for the facts only you own instead of inventing them. The name is the namesake: it resurrects dead codebases. But it's just as useful on healthy code you want understood, assessed, or made runnable. @@ -34,7 +34,7 @@ The name is the namesake: it resurrects dead codebases. But it's just as useful ## 3. The six skills + the guard -Lazarus is **six skills in three journeys** β€” *make it run* (`discover` β†’ `repair`), *assess it, then optionally fix it* (`audit` β†’ `audit-repair`), and *make it presentable, then optionally fix it* (`presentation` β†’ `presentation-repair`) β€” with a guard running across everything. Each journey is plan β†’ you approve β†’ execute, and each apply phase refuses to run without its ratified upstream report. +Lazarus is **six skills in three journeys** β€” *make it run* (`discover` β†’ `repair`), *assess it, then optionally fix it* (`audit` β†’ `audit-repair`), and *polish the repo page, then optionally fix it* (`presentation` β†’ `presentation-repair`) β€” with a guard running across everything. Each journey is plan β†’ you approve β†’ execute, and each apply phase refuses to run without its ratified upstream report. ### `discover` β€” understand (read-only) Runs in Claude Code's **Plan Mode** (read-only at the tool level β€” it physically cannot edit). It traces how the code is meant to run and writes a `DISCOVERY.md` file containing: a **repairability verdict** (`repairable` / `partially-runnable` / `not-repairable` β€” broken-but-fixable blockers are split from never-built gaps), what the app appears to do, the inferred setup/build/test/run commands, a ranked list of blockers, and a **Mechanical Definition of Done** β€” runnable assertions like *"`npm install` exits 0, the server stays up 30 seconds, this endpoint returns 200."* Then it **stops and waits for you to approve.** @@ -48,7 +48,7 @@ A separate journey that answers a different question: *should we own this?* It p ### `audit-repair` β€” act on the audit (optional, changes code behind your approval) The strategic apply phase, mirroring `discover β†’ repair`. It requires a **ratified** `CODEBASE_AUDIT.md` and executes its Β§11 Top 10 Action Items **one finding at a time** β€” ratify β†’ act β†’ verify against each item's acceptance check β€” in modernization-plan order (safety rails before refactors), behind the same guard. Its outputs are `AUDIT_`-prefixed (`AUDIT_VERIFICATION_REPORT.md`, `AUDIT_IMPLEMENTATION_SUMMARY.md`) so they never collide with repair's files. The audit never requires it β€” a report you never act on is still a complete, useful outcome. -### `presentation` β€” make it presentable (read-only, standalone) +### `presentation` β€” polish the repo page (read-only, standalone) The DevRel analog of `audit`: a read-only, project-type-aware review of the repo's **public files** β€” README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue/PR templates, markdown accessibility β€” producing one artifact, `PRESENTATION_AUDIT.md`, behind the same ratify gate. Its defining rule: **no taste-only findings.** Every finding cites a named standard (GitHub's community-profile checklist, CommonMark, WCAG, DiΓ‘taxis, the README-content research) and carries file/line evidence; a self-check gate rejects anything else. It detects the project type (Claude Code plugin / Python / Node CLI / Node library) and applies the matching conventions β€” stopping to ask rather than guessing on ambiguous signals. A durable waiver file (`.lazarus/presentation-waivers.yml`) records your deliberate choices so re-runs never nag about them. Structurally read-only: shell, network, and delegation tools are removed from its tool pool via `disallowed-tools` β€” it audits files; it cannot run commands at all. GitHub *settings* (description, topics, social preview) need `gh` and are deliberately out of scope (a future `lazarus-github` settings skill). ### `presentation-repair` β€” act on the presentation audit (optional, changes files behind your approval) @@ -142,7 +142,7 @@ You don't have to be a principal engineer to get a principal engineer's read. Th ## 10. Fast facts - **Name / tagline:** Lazarus β€” "Bring your codebase alive. Before production." A Claude Code plugin by Cognitive Code. -- **Three journeys:** `discover β†’ (you approve) β†’ repair` ("make it run"); `audit β†’ (you ratify) β†’ audit-repair` ("assess it, then optionally fix it"); `presentation β†’ (you ratify) β†’ presentation-repair` ("make it presentable, then optionally fix it"). Every report also stands alone. +- **Three journeys:** `discover β†’ (you approve) β†’ repair` ("make it run"); `audit β†’ (you ratify) β†’ audit-repair` ("assess it, then optionally fix it"); `presentation β†’ (you ratify) β†’ presentation-repair` ("polish the repo page β€” the README + community files β€” then optionally fix it"). Every report also stands alone. - **The guard:** deterministic `PreToolUse` hook, reads JSON on stdin, blocks ~25+ destructive patterns, fails closed, exit 2 = deny. - **Safety pillars:** confidence tags, mechanical Definition of Done, forensic file separation, Plan Mode read-only, human ratification gate. - **Ecosystem:** core `lazarus` + optional `lazarus-github` (audit β†’ GitHub Issues) + optional `lazarus-forge` (pre-build design review); outward-facing features are opt-in sibling plugins.