cmoriarty/braid
1
0
Fork 0
Code Issues 15 Pull requests Projects Releases Packages 1 Wiki Activity Actions

New Run as a wizard: detect OpenSpec and git flow, narrow the pipelines, and name them properly #88

New issue
Closed
opened 2026-09-27 12:01:50 -04:00 by cmoriarty · 1 comment
cmoriarty commented 2026-09-27 12:01:50 -04:00
Owner
Copy link

The New Run page (ui/src/components/NewRun.tsx) is one flat form today: Entry, Repository, Issue/Brief, Pipeline, Base branch. Every built-in pipeline is offered whatever the repository looks like, so a repo with no develop branch is still offered git-flow, and a repo that has never seen OpenSpec is offered default (which proposes an OpenSpec change) with nothing saying so.

Research, design and implement a wizard-like New Run: a short series of choices where each answer narrows what comes next, ending on a small set of pipelines that fit.

The flow

  1. Existing repository or new project. Pick a repo from the list, or choose New Project.
  2. Detect what the repository already uses. For an existing repo, Braid detects:
    • OpenSpec: e.g. an openspec/ directory (openspec/config.yaml, openspec/specs/).
    • Git flow: e.g. a develop branch next to main, and/or feature/*, release/*, hotfix/* branches, or git-flow config.
      Show what was detected so the operator can see why they're being asked what they're asked.
  3. Adopt what's missing? If the repo lacks OpenSpec and/or git flow, ask whether to introduce them. If the answer is no, only offer pipelines that don't need them (e.g. quick-fix, and a feature-branch pipeline without OpenSpec).
  4. Pick the pipeline from the narrowed list, then the work itself (Forgejo Issue or brief) and the base branch as today.

Degrade the way the pickers already do: if detection can't answer (no mirror of the repo yet, forge down), say so and fall back to offering everything, without blocking the run.

Naming

  • Heading: "What should it work on?" → "New Run".
  • Entry options: drop the "A" and use Title Case: Forgejo Issue, Feature I Describe, New Project.
  • Pipelines get a short name and a full name. default isn't a name: it is really OpenSpec on git feature branches. For example minimalist → "Abridged OpenSpec with git feature branching and automated testing". The picker shows the short name with the full name next to it (the one-line summary we have now becomes the full name, or sits next to it).
    • Renaming default touches .osf/pipeline.yaml (read as default), the osf:run label (runs default), recorded runs whose pipeline is default, and tools/drive.py. The design needs to keep old runs and repos working, e.g. by keeping default as an alias.

Gaps to look at while designing

  • The built-ins are a matrix (OpenSpec yes/no × feature branches / git flow) with holes: there's no git flow pipeline without OpenSpec, for example. Decide whether the wizard needs those filled or just says what's available.
  • What "introduce OpenSpec / git flow" means for a run: does the run do openspec init or create develop as its first step, or is that a separate prologue like new_project's?
  • Pipelines the repo defines in .osf/pipelines/*.yaml need to say (or have detected) whether they use OpenSpec / git flow so they can be filtered too.

Related: #43 (a methodology tier above graphs, picking a graph per task). This issue is the operator-facing front of that: choosing the methodology when the run starts.

The New Run page (`ui/src/components/NewRun.tsx`) is one flat form today: Entry, Repository, Issue/Brief, Pipeline, Base branch. Every built-in pipeline is offered whatever the repository looks like, so a repo with no `develop` branch is still offered `git-flow`, and a repo that has never seen OpenSpec is offered `default` (which proposes an OpenSpec change) with nothing saying so. Research, design and implement a wizard-like New Run: a short series of choices where each answer narrows what comes next, ending on a small set of pipelines that fit. ## The flow 1. **Existing repository or new project.** Pick a repo from the list, or choose New Project. 2. **Detect what the repository already uses.** For an existing repo, Braid detects: - **OpenSpec**: e.g. an `openspec/` directory (`openspec/config.yaml`, `openspec/specs/`). - **Git flow**: e.g. a `develop` branch next to `main`, and/or `feature/*`, `release/*`, `hotfix/*` branches, or git-flow config. Show what was detected so the operator can see why they're being asked what they're asked. 3. **Adopt what's missing?** If the repo lacks OpenSpec and/or git flow, ask whether to introduce them. If the answer is no, only offer pipelines that don't need them (e.g. `quick-fix`, and a feature-branch pipeline without OpenSpec). 4. **Pick the pipeline** from the narrowed list, then the work itself (Forgejo Issue or brief) and the base branch as today. Degrade the way the pickers already do: if detection can't answer (no mirror of the repo yet, forge down), say so and fall back to offering everything, without blocking the run. ## Naming - Heading: **"What should it work on?" → "New Run"**. - Entry options: drop the "A" and use Title Case: **Forgejo Issue**, **Feature I Describe**, **New Project**. - Pipelines get a **short name** and a **full name**. `default` isn't a name: it is really OpenSpec on git feature branches. For example `minimalist` → "Abridged OpenSpec with git feature branching and automated testing". The picker shows the short name with the full name next to it (the one-line summary we have now becomes the full name, or sits next to it). - Renaming `default` touches `.osf/pipeline.yaml` (read as `default`), the `osf:run` label (runs `default`), recorded runs whose pipeline is `default`, and `tools/drive.py`. The design needs to keep old runs and repos working, e.g. by keeping `default` as an alias. ## Gaps to look at while designing - The built-ins are a matrix (OpenSpec yes/no × feature branches / git flow) with holes: there's no git flow pipeline without OpenSpec, for example. Decide whether the wizard needs those filled or just says what's available. - What "introduce OpenSpec / git flow" means for a run: does the run do `openspec init` or create `develop` as its first step, or is that a separate prologue like `new_project`'s? - Pipelines the repo defines in `.osf/pipelines/*.yaml` need to say (or have detected) whether they use OpenSpec / git flow so they can be filtered too. Related: #43 (a methodology tier above graphs, picking a graph per task). This issue is the operator-facing front of that: choosing the methodology when the run starts.
cmoriarty commented 2026-09-27 17:29:52 -04:00
Author
Owner
Copy link

Shipped in e50c3a9 on main (feature 37af2bd, archived as openspec/changes/archive/2026-09-27-new-run-wizard).

New Run is now a wizard. Headed New Run, it asks Entry → Repository → Methodology → Pipeline, folding each answer to one line with change, then the issue or brief and the base branch.

  • Entry options are Forgejo Issue, Feature I Describe and New Project.
  • Detection: GET /api/repo-profile?repo= reports whether a repository has openspec/ on its default branch and a develop branch. It asks the Forgejo API for a forge repository and git for a local path. When it can't tell, it answers null with a reason, and the wizard says so and narrows nothing.
  • Introduce what's missing: the wizard asks about OpenSpec and git flow only when the repository lacks them, and asks both for a New Project. Introducing OpenSpec needs nothing extra: the run's PR carries the openspec init scaffolding. Introducing git flow sends adopt_git_flow, and admission then creates develop from the base branch (on the forge, never moving an existing one) instead of blocking.
  • Narrowing: declining OpenSpec leaves only pipelines without it. Git flow, found or introduced, leaves only the git-flow* pipelines; without it, none of them.

Naming

  • default is now thorough. default still works everywhere: old runs, osf:default, drive.py --pipeline default, .osf/pipeline.yaml.
  • Every pipeline has a full name next to its short name, e.g. minimalist: Abridged OpenSpec with feature branches and automated testing. A pipeline can declare title: and uses: {openspec, git_flow}; when it doesn't, uses is inferred from the graph.
  • New built-ins git-flow-minimalist and git-flow-quick-fix fill the git-flow side of the matrix.

Schema: version 5 adds run.adopt_git_flow, applied by osfd migrate on deploy.

Verification:

  • Full lane passes: 1856 backend, 444 vitest, 107 Playwright, including the new e2e/new-run-wizard.spec.ts.
  • Checked in a real browser against a local osfd reading the real Forgejo. Detection is right for all 71 repos: none has develop yet, and openspec-flow, soundcheck and a dozen others have OpenSpec.

Related: #43, which picks a graph per task at run time, is still open.

Shipped in `e50c3a9` on `main` (feature `37af2bd`, archived as `openspec/changes/archive/2026-09-27-new-run-wizard`). **New Run is now a wizard.** Headed **New Run**, it asks Entry → Repository → Methodology → Pipeline, folding each answer to one line with **change**, then the issue or brief and the base branch. - Entry options are **Forgejo Issue**, **Feature I Describe** and **New Project**. - **Detection:** `GET /api/repo-profile?repo=` reports whether a repository has `openspec/` on its default branch and a `develop` branch. It asks the Forgejo API for a forge repository and git for a local path. When it can't tell, it answers `null` with a reason, and the wizard says so and narrows nothing. - **Introduce what's missing:** the wizard asks about OpenSpec and git flow only when the repository lacks them, and asks both for a New Project. Introducing OpenSpec needs nothing extra: the run's PR carries the `openspec init` scaffolding. Introducing git flow sends `adopt_git_flow`, and admission then creates `develop` from the base branch (on the forge, never moving an existing one) instead of blocking. - **Narrowing:** declining OpenSpec leaves only pipelines without it. Git flow, found or introduced, leaves only the `git-flow*` pipelines; without it, none of them. **Naming** - `default` is now **`thorough`**. `default` still works everywhere: old runs, `osf:default`, `drive.py --pipeline default`, `.osf/pipeline.yaml`. - Every pipeline has a full name next to its short name, e.g. `minimalist`: *Abridged OpenSpec with feature branches and automated testing*. A pipeline can declare `title:` and `uses: {openspec, git_flow}`; when it doesn't, `uses` is inferred from the graph. - New built-ins **`git-flow-minimalist`** and **`git-flow-quick-fix`** fill the git-flow side of the matrix. **Schema:** version 5 adds `run.adopt_git_flow`, applied by `osfd migrate` on deploy. **Verification:** - Full lane passes: 1856 backend, 444 vitest, 107 Playwright, including the new `e2e/new-run-wizard.spec.ts`. - Checked in a real browser against a local osfd reading the real Forgejo. Detection is right for all 71 repos: none has `develop` yet, and openspec-flow, soundcheck and a dozen others have OpenSpec. Related: #43, which picks a graph per task at run time, is still open.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
archive/prefect-kestra-experiments
Labels
Clear labels
No items
No labels
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
cmoriarty/braid#88
No description provided.