Skip to content

English · 日本語

The roadmap workflow: ideation → implementation

How a feature travels from a rough idea to shipped, green code: the ideation skill authors a roadmap (BE) item, the implement-be skill ships it. The two are deliberate counterparts — one fills the roadmap, the other empties it — and together they form the loop every non-trivial change to Bajutsu runs through. This page explains that loop; the BE-ID mechanics it relies on are specified in ai-development.

New to contributing? Start with the contributor workflow tutorial — a hands-on, step-by-step walkthrough that runs one idea through this whole loop (and shows when to fold it into a single PR with propose-and-build). This page is the conceptual overview behind it.

Bajutsu's roadmap is not a backlog you skim past — it is the shared hub for planning, the same way a scenario YAML is the shared hub for a test. A feature is first written down as a BE (Bajutsu Evolution) item under roadmaps/, discussed and refined as a proposal, and only then built. Both halves of that journey have a dedicated skill, so the path is the same whether a human or an agent walks it.

The cycle

Cycle diagram: a rough idea goes into /ideation, which drafts a BE-XXXX proposal in both languages; CI allocates the real BE-NNNN id and sets Status: Proposal; the proposal is the spec that /implement-be plans, implements, and tests against; review and the gate flip the same item's Status to Implemented without ever moving its path.

Mermaid source 
flowchart TB
    idea(["rough idea"])
    ideation["/ideation<br/>author + think<br/>never judge"]
    proposal[["roadmaps/BE-NNNN-&lt;slug&gt;/<br/>Status: Proposal"]]
    implement["/implement-be<br/>implement<br/>gate is judge"]
    implemented[["roadmaps/BE-NNNN-&lt;slug&gt;/<br/>Status: Implemented"]]

    idea --> ideation
    ideation -->|"drafts BE-XXXX proposal<br/>(both languages)"| proposal
    proposal -.->|"CI allocates the real ID<br/>(scripts/allocate_…)"| ideation
    proposal -->|"the proposal is the spec"| implement
    implement -->|"plan → implement → test<br/>review → gate;<br/>flips Status only, the path never moves"| implemented

The two skills share the same three prime directives (CLAUDE.md) — AI authors and investigates but never judges, determinism first, app-agnostic — because they are two ends of one pipeline, not two unrelated tools. An idea that cannot be built within the directives is not a good proposal, so ideation reshapes it to fit rather than dropping it, and implement-be refuses to silently work around a directive a half-built item turns out to violate.

Authoring: the ideation skill

Invoke it with /ideation when you want to brainstorm what Bajutsu could do next, or turn a rough idea into a BE item. It is a sounding board, not a blank page: every suggestion is anchored to what is already planned, in progress, or deliberately not adopted.

  1. Ground in the existing roadmap. It reads roadmaps/README.md (what's already out of scope, unsorted ideas awaiting a BE number), architecture.md#implementation-status (so it does not "propose" something already shipped), and the BE items near your topic.
  2. Ideate with you. It offers concrete, bounded ideas and asks the questions that sharpen scope — who is it for, which tier, what is the machine-checkable outcome — pulling in adjacent items as reference points.
  3. Classify each surviving idea into one of three landings, noting which it chose: overlaps an existing item (augment that item rather than duplicate it), novel and scoped (draft a new item), or still unformed (a bullet under Unsorted ideas in both language READMEs, to promote later).
  4. Draft the new item with a placeholder ID. make new-roadmap-item SLUG=… TITLE="…" scaffolds roadmaps/BE-XXXX-<slug>/ with both language files in the canonical Swift-Evolution format; the skill fills the TBD sections and rewrites the Japanese side into natural Japanese. The literal BE-XXXX placeholder is intentional — IDs are never guessed by hand.
  5. Self-review against the CI review contract. A fresh subagent — blind to the authoring conversation, mirroring the CI reviewer's own cold start — applies the same contract the "Claude review" GitHub Actions workflow uses (.github/claude-review-prompt.md, BE-0203) to the staged diff. Every finding gets fixed, except a false positive or an already-explained trade-off (noted and left as-is), or a finding that calls for a genuine design change (escalated to you instead of attempted); capped at 3 rounds, escalating to you if it still hasn't converged by then.
  6. Verify and (only if you ask) open the PR. make check keeps the gate green even for a docs-only change; the PR body notes that CI will allocate the real ID.

The placeholder exists because IDs are permanent and monotonic, and many branches are in flight at once. Picking a number by hand races — two PRs grab the same one. The roadmap-id workflow runs scripts/allocate_roadmap_ids.py at PR time, claims the next free IDs atomically, renames BE-XXXX → BE-NNNN everywhere, and pushes the result back to the branch. Authoring stays conflict-free. The full mechanics are in ai-development.

Shipping: the implement-be skill

Invoke it with /implement-be BE-0066 (a full ID, a bare number, or a slug fragment) when you want to turn an existing proposal into shipped code. The proposal's Detailed design is the spec; the deterministic gate (make check) is the judge — never an LLM.

  1. Resolve the item and read both language files. Implementing a Proposal accepts it — this PR flips it to Implemented — so the skill says so up front. An already-Implemented, a Deferred, or a Rejected item makes it stop and confirm what you actually want — for a Rejected one, that a human has explicitly overturned the decision.
  2. Claim the tracking issue. Every open item has a GitHub issue labeled roadmap-tracking; if someone else is already assigned, the skill stops rather than duplicating work. Otherwise it self-assigns the issue before branching.
  3. Ground in the spec and the code. It reads the Detailed design and Alternatives considered (the latter records paths already rejected, often for directive reasons — do not re-propose them), opens every file the proposal links, checks implementation status, and verifies any prerequisite BE item is not itself still a proposal.
  4. Set up a focused branch off the latest origin/main (claude/be-NNNN-<slug>), staying in its lane — only the files this item needs.
  5. Plan, then confirm before writing code. A whole roadmap item is large and hard to reverse, so it gets your go-ahead on a concrete plan first: the files it will touch, the machine-checkable outcome that proves it works (and where AI is and is not allowed to sit), the tests, the docs that must move in both languages, and any tension with the prime directives.
  6. Implement to the design, matching the codebase grain — strict mypy, configured ruff, condition waits not sleep, new knobs in targets.<name> config, tests as the regression net, and bilingual docs for any documented behavior.
  7. Review and refine the diff against the repository's own review contract, .github/claude-review-prompt.md — the same lenses CI's automated reviewer applies (BE-0203), read from the contract and applied to the diff in a fresh review context rather than through a review command, so the pass depends on no installed skill. Alongside it, run the built-in simplify skill and — for a non-trivial change — the pr-review-toolkit agents. These are authoring aids: they advise the author and never judge, so directive #1 holds and no LLM touches the run/CI path. Keep re-running the review contract against the updated diff until the pass comes back empty, and open the PR (step 10) only once every real finding is fixed — capped at 3 rounds like step 5 above, escalating to you with the PR left unopened if a real finding still stands.
  8. Flip the item to Implemented. In both language files set Status: Implemented and add the Implementing PR line — nothing else to regenerate, since the dashboard reads Status straight off the item's metadata. The directory never moves (BE-0159): only the Status and its dashboard bucket change.
  9. Verify — the gate. make check must be green; never push red. If correctness genuinely depends on a Simulator/browser run, the verify skill drives it rather than claiming it works untested.
  10. Auto-open the Draft PR. Once the gate is green, the skill opens the PR itself instead of waiting for a request — its output is always a self-contained, gate-green change. The title carries the [BE-NNNN] prefix, and a follow-up push fills the Implementing PR line with the real number.

Why two skills, not one

Keeping authoring and shipping separate mirrors Bajutsu's own core boundary. ideation lives in the author role — it thinks, proposes, and reshapes, and its output (a proposal) is never a verdict. implement-be lives in the builder role — it turns a spec into code that a deterministic gate either passes or fails. The same way Bajutsu keeps AI out of the pass/fail judgment of a test run, the workflow keeps the open-ended part of planning (what should we build, is this idea sound) cleanly apart from the closed part of shipping (does this code meet the spec and pass the gate). A proposal that has been argued into shape is a far better spec than a one-line ticket, and an implementation bounded by that spec is far easier to review than a freehand change. The loop is the point.

See also

  • ai-development — the parallel-work rules, the gate, and the strict BE-ID lifecycle (Status ⇒ dashboard bucket, flat one-directory layout, permanent IDs) both skills depend on.
  • roadmaps/README — how to add a roadmap item, what's already out of scope, and unsorted ideas awaiting a BE number.
  • concepts — the determinism and AI-boundary principles the prime directives encode.
  • CLAUDE.md — the working agreement the prime directives come from.