EduarD3V/bullet
Watch
1
0
Fork
You've already forked bullet
 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

docs: add docs/ROADMAP.md stub #1

New issue
Open
opened 2026-10-12 15:46:01 +02:00 by gotoi-agent · 5 comments
gotoi-agent commented 2026-10-12 15:46:01 +02:00
Collaborator
Copy link

Add a short docs/ROADMAP.md (10-20 lines): the three next things bullet needs (GitHub Actions mode, merge:auto safety rails, multi-forge token docs). Plain markdown, no build impact. Refs the plug-and-play goal in README.md.

Add a short `docs/ROADMAP.md` (10-20 lines): the three next things bullet needs (GitHub Actions mode, merge:auto safety rails, multi-forge token docs). Plain markdown, no build impact. Refs the plug-and-play goal in README.md.
gotoi-agent commented 2026-10-12 16:02:57 +02:00
Author
Collaborator
Copy link

bullet: coder launched on branch issue/1-docs-add-docs-roadmap-md-stub (model nan/deepseek-v4-flash).

bullet: coder launched on branch `issue/1-docs-add-docs-roadmap-md-stub` (model `nan/deepseek-v4-flash`).
gotoi-agent commented 2026-10-12 16:04:08 +02:00
Author
Collaborator
Copy link

bullet: coder launched on branch issue/1-docs-add-docs-roadmap-md-stub (model nan/deepseek-v4-flash).

bullet: coder launched on branch `issue/1-docs-add-docs-roadmap-md-stub` (model `nan/deepseek-v4-flash`).
gotoi-agent commented 2026-10-12 16:04:38 +02:00
Author
Collaborator
Copy link

Claimed — branch issue/1-docs-add-docs-roadmap-md-stub. Doing: add docs/ROADMAP.md (10-20 lines), 3 near-term items, gap map vs the plug-and-play goal.

Claimed — branch `issue/1-docs-add-docs-roadmap-md-stub`. Doing: add docs/ROADMAP.md (10-20 lines), 3 near-term items, gap map vs the plug-and-play goal.
gotoi-agent commented 2026-10-12 16:04:54 +02:00
Author
Collaborator
Copy link

Plan — issue #1: docs: add docs/ROADMAP.md stub

Restated goal

Add one new file, docs/ROADMAP.md: a short (10–20 line) plain-markdown roadmap naming the next
three things bullet needs — GitHub Actions mode, merge:auto safety rails, multi-forge token
docs — with a one-line "why it's not there yet" per item, and a pointer back to the plug-and-play
goal (README.md headline "Plug and play autonomous issue→PR fleet" + docs/PLUG-AND-PLAY.md).

Done = docs/ROADMAP.md exists, is 10–20 lines, contains the three named items, references the
plug-and-play goal, no other file changed, bash selfcheck.sh still green, one commit on
issue/1-docs-add-docs-roadmap-md-stub, and Refs #1 in the commit message.

Scope

Files I will change (exactly one):

  • docs/ROADMAP.md (new)

Files I will not touch:

  • README.md — the issue asks the roadmap to reference the goal, not to link it from the README.
    Adding a "Roadmap" row/link to the README table is scope creep; left for a human to request.
  • docs/PLUG-AND-PLAY.md, docs/STATE-MACHINE.md, bullet.yaml.example, lib/, orchestrator/,
    prompts/, skills/, selfcheck.sh, bullet.
  • No tests, no config, no code. Docs-only, zero build impact (as the issue states).

Facts the content rests on (already verified in-repo, no invention):

  • forge: github + url: https://api.github.com is supported — docs/PLUG-AND-PLAY.md §GitHub,
    lib/forge.sh branches per forge. What is missing is running bullet on a hosted runner
    (today: local cron + tmux + worktrees, per README quickstart) → item 1.
  • merge: auto exists as a config key and is honoured by lib/config.sh (MERGE_MODE) and
    lib/forge.sh (forge_merge_pr); README design rule 5 says "Humans merge. (Set merge: auto if
    you really want the fleet to close the loop itself.)" No precondition checks around the auto path
    → item 2.
  • Auth today is a single BULLET_TOKEN (or BULLET_BASIC=user:pass), documented only as "token
    with issues+PR write"; per-forge scopes/permissions are not spelled out anywhere → item 3.

Ordered tasks (each with its verify command)

  1. Write docs/ROADMAP.md — title, one-line framing tying the roadmap to the plug-and-play
    goal (cite README.md / docs/PLUG-AND-PLAY.md), then the three items as bolded names with
    1–2 line bodies, then a two-line "Not on the roadmap" / "Shipping order" tail.
    Verify: wc -l docs/ROADMAP.md → between 10 and 20; rg -c -i 'plug and play' docs/ROADMAP.md → ≥1.
  2. Check the three items are present and the diff is docs-only.
    Verify: rg -n -i 'github actions|merge:auto|token' docs/ROADMAP.md; git status --porcelain → only ?? docs/ROADMAP.md.
  3. Commit. git add docs/ROADMAP.md && git commit -m 'docs: add docs/ROADMAP.md stub (Refs #1)'.
    Verify: git log --oneline -1; git status --short → clean.
  4. Run the gate. Verify: bash selfcheck.sh → exit 0, prints selfcheck: all green.

Open questions (assumption I am proceeding on)

  • Does "merge:auto safety rails" mean new config keys or hardening of the existing merge: auto?
    Assumption: hardening — a roadmap entry is a statement of need, not a design. I name the rails
    (reviewer verdict CLEAN required, gates green on the final tree, trunk untouched, idempotent
    re-check before merge) without inventing key names.
  • "GitHub Actions mode" — replace cron+tmux, or an alternative scheduler?
    Assumption: alternative execution mode for the same bullet tick loop; per-issue runner isolation
    is the honest blocker to state, since tmux + local worktrees do not exist on a hosted runner.
  • "Multi-forge token docs" — one page or a section?
    Assumption: docs work (forge-neutral token/permission matrix: Forgejo scopes vs GitHub
    fine-grained PAT, bot identity, one token per target repo), not code. I note the doc, do not write it.
  • Is 20 lines a hard cap? Assumption: the issue's "10-20 lines" is the target; I aim ≤20 and check with wc -l.

Risk

  • Gate risk: near zero — selfcheck.sh runs bash -n over shell files, parses bullet.yaml.example,
    and composes prompts. A new markdown file under docs/ cannot affect it (no glob scans docs/).
    Boring fallback if it goes red: git stash-free path — the file is untracked and self-contained,
    so rm docs/ROADMAP.md restores the previous state, then report the exact error line.
  • Fidelity risk: writing a design doc instead of a stub (item drift into RFC territory). Mitigation:
    1–2 lines per item, no invented APIs/config keys.
  • merge:auto wording risk: claiming rails exist. Mitigation: phrase all three items as
    "needed", never as "supported".
  • No push, no branch switch, Refs #1 only, no closing keywords.
# Plan — issue #1: docs: add docs/ROADMAP.md stub ## Restated goal Add one new file, `docs/ROADMAP.md`: a short (10–20 line) plain-markdown roadmap naming the next three things bullet needs — **GitHub Actions mode**, **merge:auto safety rails**, **multi-forge token docs** — with a one-line "why it's not there yet" per item, and a pointer back to the plug-and-play goal (`README.md` headline "Plug and play autonomous issue→PR fleet" + `docs/PLUG-AND-PLAY.md`). Done = `docs/ROADMAP.md` exists, is 10–20 lines, contains the three named items, references the plug-and-play goal, no other file changed, `bash selfcheck.sh` still green, one commit on `issue/1-docs-add-docs-roadmap-md-stub`, and `Refs #1` in the commit message. ## Scope Files I will change (exactly one): - `docs/ROADMAP.md` (new) Files I will **not** touch: - `README.md` — the issue asks the roadmap to *reference* the goal, not to link it from the README. Adding a "Roadmap" row/link to the README table is scope creep; left for a human to request. - `docs/PLUG-AND-PLAY.md`, `docs/STATE-MACHINE.md`, `bullet.yaml.example`, `lib/`, `orchestrator/`, `prompts/`, `skills/`, `selfcheck.sh`, `bullet`. - No tests, no config, no code. Docs-only, zero build impact (as the issue states). Facts the content rests on (already verified in-repo, no invention): - `forge: github` + `url: https://api.github.com` is supported — `docs/PLUG-AND-PLAY.md` §GitHub, `lib/forge.sh` branches per forge. What is missing is *running* bullet on a hosted runner (today: local cron + tmux + worktrees, per README quickstart) → item 1. - `merge: auto` exists as a config key and is honoured by `lib/config.sh` (`MERGE_MODE`) and `lib/forge.sh` (`forge_merge_pr`); README design rule 5 says "Humans merge. (Set `merge: auto` if you really want the fleet to close the loop itself.)" No precondition checks around the auto path → item 2. - Auth today is a single `BULLET_TOKEN` (or `BULLET_BASIC=user:pass`), documented only as "token with issues+PR write"; per-forge scopes/permissions are not spelled out anywhere → item 3. ## Ordered tasks (each with its verify command) 1. **Write `docs/ROADMAP.md`** — title, one-line framing tying the roadmap to the plug-and-play goal (cite `README.md` / `docs/PLUG-AND-PLAY.md`), then the three items as bolded names with 1–2 line bodies, then a two-line "Not on the roadmap" / "Shipping order" tail. Verify: `wc -l docs/ROADMAP.md` → between 10 and 20; `rg -c -i 'plug and play' docs/ROADMAP.md` → ≥1. 2. **Check the three items are present and the diff is docs-only.** Verify: `rg -n -i 'github actions|merge:auto|token' docs/ROADMAP.md`; `git status --porcelain` → only `?? docs/ROADMAP.md`. 3. **Commit.** `git add docs/ROADMAP.md && git commit -m 'docs: add docs/ROADMAP.md stub (Refs #1)'`. Verify: `git log --oneline -1`; `git status --short` → clean. 4. **Run the gate.** Verify: `bash selfcheck.sh` → exit 0, prints `selfcheck: all green`. ## Open questions (assumption I am proceeding on) - *Does "merge:auto safety rails" mean new config keys or hardening of the existing `merge: auto`?* Assumption: hardening — a roadmap entry is a statement of need, not a design. I name the rails (reviewer verdict CLEAN required, gates green on the final tree, trunk untouched, idempotent re-check before merge) without inventing key names. - *"GitHub Actions mode" — replace cron+tmux, or an alternative scheduler?* Assumption: alternative execution mode for the same `bullet tick` loop; per-issue runner isolation is the honest blocker to state, since tmux + local worktrees do not exist on a hosted runner. - *"Multi-forge token docs" — one page or a section?* Assumption: docs work (forge-neutral token/permission matrix: Forgejo scopes vs GitHub fine-grained PAT, bot identity, one token per target repo), not code. I note the doc, do not write it. - *Is 20 lines a hard cap?* Assumption: the issue's "10-20 lines" is the target; I aim ≤20 and check with `wc -l`. ## Risk - **Gate risk:** near zero — `selfcheck.sh` runs `bash -n` over shell files, parses `bullet.yaml.example`, and composes prompts. A new markdown file under `docs/` cannot affect it (no glob scans `docs/`). Boring fallback if it goes red: `git stash`-free path — the file is untracked and self-contained, so `rm docs/ROADMAP.md` restores the previous state, then report the exact error line. - **Fidelity risk:** writing a design doc instead of a stub (item drift into RFC territory). Mitigation: 1–2 lines per item, no invented APIs/config keys. - **`merge:auto` wording risk:** claiming rails *exist*. Mitigation: phrase all three items as "needed", never as "supported". - No push, no branch switch, `Refs #1` only, no closing keywords.
gotoi-agent commented 2026-10-12 16:05:49 +02:00
Author
Collaborator
Copy link

DONE — branch issue/1-docs-add-docs-roadmap-md-stub, commit dfb7eb9 (docs: add docs/ROADMAP.md stub (Refs #1)), 1 file / +20 lines, tree clean, not pushed.

  • bash selfcheck.sh — PASS (exit 0, selfcheck: all green)
  • git diff --check — PASS
  • wc -l docs/ROADMAP.md — 20 (issue asked 10–20)
  • three named items present (GitHub Actions mode, merge: auto safety rails, multi-forge token docs) + plug-and-play ref to README.md

Human decisions left: README row/link for the roadmap, whether merge: auto rails become enforced checks in orchestrator/publish.sh, and whether the suggested order 3 → 2 → 1 is right.

DONE — branch `issue/1-docs-add-docs-roadmap-md-stub`, commit `dfb7eb9` (`docs: add docs/ROADMAP.md stub (Refs #1)`), 1 file / +20 lines, tree clean, not pushed. - `bash selfcheck.sh` — PASS (exit 0, `selfcheck: all green`) - `git diff --check` — PASS - `wc -l docs/ROADMAP.md` — 20 (issue asked 10–20) - three named items present (GitHub Actions mode, `merge: auto` safety rails, multi-forge token docs) + plug-and-play ref to README.md Human decisions left: README row/link for the roadmap, whether `merge: auto` rails become enforced checks in `orchestrator/publish.sh`, and whether the suggested order 3 → 2 → 1 is right.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
bullet:blocked

   
bullet:done

   
bullet:queued

   
bullet:review

   
bullet:running
No labels
bullet:blocked
bullet:done
bullet:queued
bullet:review
bullet:running
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
EduarD3V/bullet#1
No description provided.