Problem
The CLI README reads like developer documentation, not a discovery page. The opening line — "Capture prompts and events from AI coding assistants." — describes the feature but doesn't answer why a developer would want it. There's no problem statement, no GitHub stars badge (the primary social proof signal developers look for), and two correctness issues: the quick-start block references the wrong skills path (`/.claude/commands/` instead of `/.claude/skills/`), and the environment-switching section presents `config set-env` and `config env use` as ambiguous alternatives rather than making clear one is a shorthand.
Developers landing on this repo from a GitHub search, HN post, or a link need to immediately understand why they'd want this. The current README doesn't give them that.
Solution
Four targeted changes — no structural rewrites:
- Opening hook: Replace the dry feature description with a problem-first statement that explains what's being lost and what PromptConduit fixes
- Stars badge: Add `![GitHub Stars]` badge alongside existing CI/License/Go badges
- Skills path fix: Line 21 says `
/.claude/commands/` — correct to `/.claude/skills/`
- set-env clarity: Show `config env use` as the primary command, `config set-env` as the shorthand alias
Business Impact
- First impression for developers landing from GitHub search, HN, or links — better opening = more installs
- Stars badge signals traction and reduces "is this abandoned?" hesitation
- Path fix prevents confusion and failed skill installs for new users following the quick-start
Acceptance Criteria
Technical Notes
- Files affected: `README.md`
- Dependencies: none
- Breaking changes: none
Agent Context
- change-type: docs
- risk-level: low
- test-coverage: README-only, no automated tests applicable
- rollback-plan: revert README.md
Workflow Progress
```mermaid
graph LR
A[Analyze] --> B[Issue] --> C[Branch] --> D[Implement] --> E[PR] --> F[Review] --> G[CI] --> H[Merge] --> I[Deploy] --> J[Shipped]
classDef done fill:#22c55e,stroke:#16a34a,color:#fff
classDef active fill:#eab308,stroke:#ca8a04,color:#fff
classDef todo fill:#d1d5db,stroke:#9ca3af,color:#fff
class A,B,C,D,E,F,G,H,I,J done
```
Problem
The CLI README reads like developer documentation, not a discovery page. The opening line — "Capture prompts and events from AI coding assistants." — describes the feature but doesn't answer why a developer would want it. There's no problem statement, no GitHub stars badge (the primary social proof signal developers look for), and two correctness issues: the quick-start block references the wrong skills path (`
/.claude/commands/` instead of `/.claude/skills/`), and the environment-switching section presents `config set-env` and `config env use` as ambiguous alternatives rather than making clear one is a shorthand.Developers landing on this repo from a GitHub search, HN post, or a link need to immediately understand why they'd want this. The current README doesn't give them that.
Solution
Four targeted changes — no structural rewrites:
/.claude/commands/` — correct to `/.claude/skills/`Business Impact
Acceptance Criteria
Technical Notes
Agent Context
Workflow Progress
```mermaid
graph LR
A[Analyze] --> B[Issue] --> C[Branch] --> D[Implement] --> E[PR] --> F[Review] --> G[CI] --> H[Merge] --> I[Deploy] --> J[Shipped]
classDef done fill:#22c55e,stroke:#16a34a,color:#fff
classDef active fill:#eab308,stroke:#ca8a04,color:#fff
classDef todo fill:#d1d5db,stroke:#9ca3af,color:#fff
class A,B,C,D,E,F,G,H,I,J done
```