dwmkerr / dwmkerr/openspec-flow
feat: make README modification opt-out, and stop appending after `## License`
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 0
- Avg merge
- 3d 23h
- Merged PRs (30d)
- 1
Description
## Problem
`install` always writes the README. The only flags are `--yes`, `--force`, `--path` and `--broker` — there is no way to scaffold the shim without touching it.
Installing on [dwmkerr/signalbox](https://github.com/dwmkerr/signalbox/pull/74) showed two problems with what it writes.
**The badge lands above the title.** signalbox opens with a centered hero — `
` and a `
` badge row. `insertBadgeUnderTitle` finds no markdown H1 outside a code fence, so it takes the prepend path and the badge ends up as line 1, left-aligned, above the product name and duplicating the existing badge row.
**The block lands after `## License`.** `planReadme` appends at end of file. A README conventionally closes with the licence, so resuming afterwards with label and Actions-secret setup reads as an accident.
There is also a content question. The block explains what openspec-flow is and which secret to set. That is contributor and maintainer material — arguably `CONTRIBUTING.md` and `docs/`, not the front page of the host project.
## Proposal
1. `--no-readme` to skip the README action entirely. Shim-only installs are a legitimate case, and today the only workaround is deleting the content and leaving the empty marker pairs so the three-state model keeps it out.
2. When no markdown H1 exists outside a fence, prepending is the wrong fallback. Either skip the badge and say so in the report, or detect an existing centered badge row and insert there.
3. Insert the managed block before `## License` rather than at end of file, falling back to append when there is no licence heading.
## Notes
The three-state marker model is good and does the right thing on re-runs — this is about the first write, not idempotency.
Same applies to the App-install path in `src/app-install/`, which runs the same planner against a remote tree.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the install entry point and the README planner, including insertBadgeUnderTitle and planReadme; then inspect the corresponding App-install path in src/app-install/. Run the existing install or README tests if available, and verify --no-readme skips the action, badge handling avoids the stated fallback problem, and the managed block is placed before ## License or appended when no licence heading exists.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100