feature_machine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4b036261f92e29292d948f5bbef5a4d84d5a1bd3323d8cde92b6ae498c45f2f
+  data.tar.gz: 4800b671dac9fa5b1840ff84f513de37eeb198993c87833f68ea54f9bede0c7f
+SHA512:
+  metadata.gz: 1ba4481ff6c8dcb0892de61b6b2cf1280c898c6057ce9734ce8feaac6bc839b1461a90196d7c45eb656395e83188e0fca5d6ecb0d9610034fdbab06cd54cdf61
+  data.tar.gz: 83f8946ce62ea59a18f41c96130bee8195097156b0e6202296ec1edfb6d0935a0fbf67dfea15515b21da112dcb55867d103c4127d27ee2dee6e79cce9d5f5b77

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (2026-11-09)
+
+First public release.
+
+- Mountable engine: feature requests and bug reports in, triage, work items out.
+- Roadmap page and JSON API, maintainer API, and an MCP server for agents.
+- `rails g feature_machine:install` initializer and `feature_machine:install:migrations`.
+  With Rails' authentication generator present, the initializer reads the
+  session cookie for `current_user`, and the generator warns when there's no
+  root route for sign-in to land on.
+- Optional embeddings (pgvector via neighbor) for duplicate detection, and a
+  RubyLLM drafter and judge behind `FeatureMachine.configure`.
+- Maintainer MCP tools (`list_work_items`, `get_work_item`, `update_work_item`)
+  so a coding agent can pick up planned items and attach a pull request.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentino Stoll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# feature_machine
+
+Feature requests, work items, and the judge pipeline, packaged as a Rails engine.
+
+Your users file feature requests and bug reports, on your site or through
+their own agents over MCP. You triage them into work items, a judge ranks and
+groups them, and your own coding agent can pick up a planned item over MCP and
+attach the pull request for you to approve.
+
+## Requirements
+
+- Ruby 3.3+, Rails 8.1+
+- Postgres with the pgvector extension
+- `ruby_llm` 2.1+ (only called if you name a model; see [Models](#models))
+
+## Install
+
+```ruby
+# Gemfile
+gem "feature_machine"
+```
+
+```
+bundle install
+bin/rails g feature_machine:install
+bin/rails feature_machine:install:migrations
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/feature_machine.rb` and draws the
+engine's routes into `config/routes.rb`:
+
+```ruby
+feature_machine_routes :web        # /feature-requests, /bug-reports, /roadmap
+namespace :admin do
+  feature_machine_routes :admin    # /admin/triage, /admin/work_items
+end
+namespace :api, defaults: { format: :json } do
+  feature_machine_routes :api      # /api/feature_requests, /api/bug_reports, /api/roadmap,
+end                                # /api/work_items, /api/maintainer/feature_requests
+feature_machine_routes :mcp        # POST /mcp, for agents
+```
+
+Then tell the engine three things about your app in the initializer:
+
+```ruby
+FeatureMachine.configure do |config|
+  # Who is signed in. With Rails' authentication generator:
+  config.current_user = ->(request) { Session.find_by(id: request.cookie_jar.signed[:session_id])&.user }
+  # Who may triage. The work-items migration adds users.admin, so the default works.
+  config.admin = ->(user) { user.admin? }
+  # Bearer token -> credential: any object answering `user` and `allows?(scope)`
+  # for "read", "write" and "maintainer". Without it, agents can't connect.
+  config.authenticate_api = ->(token) { ApiToken.authenticate(token) }
+end
+```
+
+## Upgrading an app that drew the routes by hand
+
+The route macro now draws everything the engine ships: bug reports, the
+roadmap, triage, attachments, and their APIs. If your `config/routes.rb` still
+draws any of those next to `feature_machine_routes`, delete your copies, or
+Rails stops at boot with "Invalid route name, already in use".
+
+The engine's controllers no longer inherit `Admin::BaseController` or
+`Api::BaseController` on their own. If yours add filters, a layout or headers
+the engine's pages should keep, point the engine at them:
+
+```ruby
+config.admin_parent_controller = "Admin::BaseController"
+config.api_parent_controller   = "Api::BaseController"
+```
+
+Your API base keeps its own `render_error`. The engine reads the signed-in API
+user through its own `api_user`, so your `current_user` is left alone.
+
+## Host contract
+
+That is everything a fresh `rails new` app needs. The engine brings its own
+admin and API base controllers, so the host doesn't need `current_user`,
+`Admin::BaseController`, `Api::BaseController` or a `has_many` on its user
+model.
+
+- **Postgres with pgvector.** The migrations enable the `vector` extension.
+- **A `users` table.** `feature_requests.user_id` references it, and the
+  work-items migration adds `users.admin`. Name another model with
+  `config.user_class`.
+- **Pages inherit your `ApplicationController`**, so your layout and auth
+  filters apply. Signed-out visitors go to `new_session_path` when you have one
+  (`config.sign_in_path`) and get a 401 otherwise. To inherit something else,
+  set `config.parent_controller`, `config.admin_parent_controller` or
+  `config.api_parent_controller`. An API base of your own keeps its own
+  `render_error` and error handling.
+- **The engine's pages use `cn-*` classes and ship plain default styles for
+  them**, inlined in a `@layer feature_machine` block, so a host without a
+  design system still renders cleanly and any `cn-*` rule of yours wins
+  without `!important`. Set `config.default_stylesheet = false` if your own
+  stylesheet covers them all. They show their own flash notices,
+  because a new app's layout doesn't; set `config.flash_in_pages = false` if
+  yours does.
+- **Your own roadmap or bug board** replaces the engine's by pointing
+  `config.roadmap_path` (and friends) at it.
+- **An MCP server of your own** can skip `feature_machine_routes :mcp` and add
+  `FeatureMachine::Mcp.for(credential)` to its tool list instead. A browser
+  session cookie is never an MCP credential; only bearer tokens are.
+
+### Models
+
+Embeddings, the spec drafter and the triage judge are each off until you name a
+RubyLLM model (`config.embedding_model`, `config.drafter_model`,
+`config.judgment_model`). If a model is named but its provider key is missing
+or the call fails, the feature steps aside: requests are still filed, triage
+shows unranked groups, and forming a work item writes a plain digest instead
+of a spec.
+
+The triage judge uses RubyLLM's structured judgments, which only some providers
+implement: OpenAI, Ollama, and TypeSafe's Jev models in ruby_llm 2.1. Pick a
+`judgment_model` one of them serves. A chat model named through OpenRouter
+can't judge: triage logs a warning and stays unranked.
+
+OpenRouter does serve Jev's judgment API, so an OpenRouter key is enough:
+
+```ruby
+RubyLLM.configure do |c|
+  c.typesafe_api_base = "https://openrouter.ai/api"
+  c.typesafe_api_key  = ENV["OPENROUTER_API_KEY"]
+end
+FeatureMachine.config.judgment_model = "jev-latest"
+```
+
+For a local
+[Jev-compatible server](https://rubyllm.com/configuration-providers/#jev-compatible-apis),
+point `typesafe_api_base` at it instead and set
+`config.judgment_provider = :typesafe`, so the server's own model id resolves
+without a registry entry. Embeddings and the drafter work on any provider RubyLLM
+supports, including OpenRouter (set `config.drafter_provider = :openrouter`).
+
+Requests filed before `embedding_model` was set never got an embedding, and
+triage leaves them out of every group. Embed them once you switch it on:
+
+```
+bin/rails feature_machine:embed_requests
+```
+
+`bin/rails feature_machine:calibrate_judge` checks your `judgment_model`
+against mutated cases: paraphrases mustn't move an answer, and changes that
+alter the meaning must. It spends tokens, so it never runs in CI.
+In November 2026, `jev-latest` held 18 of 18. Rerun it when you change models.
+
+## Agents over MCP
+
+`feature_machine_routes :mcp` serves `POST /mcp`. Agents authenticate with a
+bearer token through `config.authenticate_api`; a browser session cookie is
+never accepted there.
+
+Any token with `read` (and `write` for filing) sees:
+
+| Tool | Does |
+| --- | --- |
+| `list_feature_requests` | The user's own requests, with status and the maintainer's note |
+| `request_feature` | File a request on the user's behalf |
+| `list_bug_reports` | The user's own bug reports, with status and note |
+| `report_bug` | File a bug on the user's behalf |
+| `read_roadmap` | In-progress and planned work, then the changelog |
+
+A `maintainer` token whose user also passes `config.admin` additionally sees
+`list_work_items`, `get_work_item` and `update_work_item`. Those aren't
+advertised to anyone else, and the engine re-checks `config.admin` on every
+maintainer call rather than trusting the token's scope alone. An agent can
+move an item through its statuses and attach a pull request, but it can't
+edit the spec, approve drafts or decline work.
+
+## Configuration reference
+
+All set in `config/initializers/feature_machine.rb`. Lambdas are called per
+request or per record; strings naming classes are constantized lazily, so the
+initializer never autoloads app code.
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `current_user` | `->(request) { nil }` | The signed-in user for a request |
+| `admin` | `user.admin?` if defined | May this user triage? |
+| `authenticate_api` | `nil` | Bearer token to credential (`user`, `allows?(scope)`). `nil` = no API or MCP access |
+| `session_auth` | `true` | Let a browser session act as a credential on the JSON API (never MCP) |
+| `user_class` | `"User"` | The model `feature_requests.user_id` points at |
+| `user_label` | `"user #<id>"` | How a requester is named on admin pages and in specs |
+| `product_name` | `"this app"` | Used in copy and error messages |
+| `product_blurb` | `product_name` | One line describing the product to the drafter |
+| `token_help_url` | `nil` | Where scope errors tell users to get a token |
+| `protected_resource_url` | `nil` | OAuth protected-resource metadata URL for 401 `WWW-Authenticate` |
+| `embedding_model` | `nil` | RubyLLM embedding model. `nil` = no similarity grouping |
+| `drafter_model`, `drafter_provider`, `drafter_fallbacks` | `nil`, `nil`, `[]` | Chat model that writes work-item specs. `nil` = plain digest |
+| `judgment_model`, `judgment_provider` | `nil`, `nil` | Structured-judgment model for triage. `nil` = unranked |
+| `on_status_change` | `nil` | `->(request) { ... }` after a request's status changes (mail the requester, etc.) |
+| `parent_controller` | `"ApplicationController"` | Base for engine pages |
+| `admin_parent_controller` | `parent_controller` | Base for engine admin pages |
+| `api_parent_controller` | `"ActionController::API"` | Base for engine API controllers |
+| `layout` | host's own | Layout for engine pages; `"feature_machine"` is a minimal standalone shell |
+| `admin_nav_partial` | `nil` | Host partial rendered atop engine admin pages, e.g. `"admin/nav"` |
+| `sign_in_path` | `new_session_path` if drawn | `->(controller) { ... }` where signed-out visitors go |
+| `flash_in_pages` | `true` | Engine pages render their own flash notices |
+| `default_stylesheet` | `true` | Engine pages inline default `cn-*` styles (in a CSS layer your rules override) |
+| `roadmap_path`, `bug_reports_path`, `new_bug_report_path`, `admin_triage_path` | engine's pages | `->(view, ...) { ... }` to link your own pages instead; `nil` drops the link |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/app/assets/feature_machine/default.css

@@ -0,0 +1,62 @@
+/* feature_machine default styles for the cn-* classes its views use.
+   Rendered inline once per engine page unless config.default_stylesheet is
+   false. Everything sits in @layer feature_machine, and layered rules lose
+   to unlayered ones, so any host stylesheet that defines a cn-* class wins
+   without !important. Colors come from the shadcn-style custom properties
+   (--background, --foreground, --muted-foreground, --border, --primary,
+   --destructive, --radius) when the host has them, with neutral fallbacks. */
+@layer feature_machine {
+  .cn-container { max-width: 48rem; margin: 0 auto; padding: 2rem 1rem; font-family: system-ui, sans-serif; color: var(--foreground, #18181b); line-height: 1.5; }
+  .cn-font-heading { font-weight: 600; letter-spacing: -0.01em; }
+
+  .cn-page-header { margin-bottom: 1.5rem; }
+  .cn-page-header-eyebrow { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted-foreground, #71717a); margin: 0; }
+  .cn-page-header-title { font-size: 1.75rem; margin: 0.25rem 0; }
+  .cn-page-header-lede { color: var(--muted-foreground, #71717a); margin: 0; }
+
+  .cn-button { display: inline-flex; align-items: center; gap: 0.375rem; border: 1px solid transparent; border-radius: var(--radius, 0.375rem); font: inherit; font-size: 0.875rem; font-weight: 500; text-decoration: none; cursor: pointer; }
+  .cn-button-size-default { padding: 0.5rem 1rem; }
+  .cn-button-size-sm { padding: 0.25rem 0.625rem; font-size: 0.8125rem; }
+  .cn-button-variant-default { background: var(--primary, #18181b); color: var(--primary-foreground, #fafafa); }
+  .cn-button-variant-outline { background: transparent; border-color: var(--border, #e4e4e7); color: inherit; }
+  .cn-button-variant-ghost { background: transparent; color: inherit; }
+  .cn-button-variant-ghost:hover, .cn-button-variant-outline:hover { background: var(--accent, #f4f4f5); }
+  .cn-button-variant-destructive { background: var(--destructive, #dc2626); color: #fff; }
+
+  .cn-field { display: flex; flex-direction: column; gap: 0.375rem; margin-bottom: 1rem; }
+  .cn-label, .cn-field-label { font-size: 0.875rem; font-weight: 500; }
+  .cn-field-description { font-size: 0.8125rem; color: var(--muted-foreground, #71717a); margin: 0; }
+  .cn-field-error { font-size: 0.8125rem; color: var(--destructive, #dc2626); margin: 0; }
+  .cn-input, .cn-textarea, .cn-native-select { font: inherit; padding: 0.5rem 0.75rem; border: 1px solid var(--input, var(--border, #e4e4e7)); border-radius: var(--radius, 0.375rem); background: var(--background, #fff); color: inherit; }
+  .cn-textarea { min-height: 6rem; resize: vertical; }
+
+  .cn-alert { border: 1px solid var(--border, #e4e4e7); border-radius: var(--radius, 0.375rem); padding: 0.75rem 1rem; margin-bottom: 1rem; }
+  .cn-alert-variant-destructive { border-color: var(--destructive, #dc2626); color: var(--destructive, #dc2626); }
+  .cn-alert-title { font-weight: 600; margin: 0; }
+  .cn-alert-description { margin: 0.25rem 0 0; }
+  .cn-flash, .feature-machine-flash { padding: 0.5rem 0.75rem; border-radius: var(--radius, 0.375rem); background: var(--muted, #f4f4f5); }
+
+  .cn-empty { text-align: center; padding: 3rem 1rem; border: 1px dashed var(--border, #e4e4e7); border-radius: var(--radius, 0.375rem); }
+  .cn-empty-header, .cn-empty-content { display: flex; flex-direction: column; align-items: center; gap: 0.5rem; }
+  .cn-empty-media-icon { width: 2.5rem; height: 2.5rem; color: var(--muted-foreground, #71717a); }
+  .cn-empty-title { font-weight: 600; margin: 0; }
+  .cn-empty-description { color: var(--muted-foreground, #71717a); margin: 0; }
+
+  .cn-entry-list, .cn-relation-list, .cn-spec-evidence-list { list-style: none; margin: 0; padding: 0; }
+  .cn-entry-section { margin: 1.5rem 0; }
+  .cn-entry-section-title { font-size: 1.125rem; margin: 0 0 0.5rem; }
+  .cn-nr-entry { border-bottom: 1px solid var(--border, #e4e4e7); padding: 1rem 0; }
+  .cn-nr-entry-title-row { display: flex; align-items: baseline; justify-content: space-between; gap: 0.75rem; }
+  .cn-nr-entry-title { font-weight: 600; margin: 0; }
+  .cn-nr-entry-summary { margin: 0.25rem 0; }
+  .cn-nr-entry-meta { display: flex; flex-wrap: wrap; gap: 0.375rem; font-size: 0.8125rem; color: var(--muted-foreground, #71717a); }
+  .cn-nr-entry-status { font-size: 0.75rem; padding: 0.125rem 0.5rem; border-radius: 999px; background: var(--muted, #f4f4f5); }
+  .cn-nr-entry-actions, .cn-review-panel-actions, .cn-triage-bucket-actions { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 0.5rem; }
+
+  .cn-triage-bucket, .cn-review-panel { border: 1px solid var(--border, #e4e4e7); border-radius: var(--radius, 0.375rem); padding: 1rem; margin-bottom: 1rem; }
+  .cn-triage-bucket-header { display: flex; justify-content: space-between; gap: 0.75rem; }
+  .cn-triage-bucket-title { font-weight: 600; margin: 0; }
+  .cn-triage-bucket-score, .cn-triage-bucket-demand, .cn-triage-summary, .cn-review-panel-lede { font-size: 0.8125rem; color: var(--muted-foreground, #71717a); }
+  .cn-triage-bucket-flag { font-size: 0.75rem; padding: 0.125rem 0.5rem; border-radius: 999px; background: var(--muted, #f4f4f5); }
+  .cn-triage-bucket-flag-warn { background: #fef3c7; color: #92400e; }
+}

data/app/controllers/api/feature_machine/base_controller.rb

@@ -0,0 +1,109 @@
+# The engine's API controllers authenticate from the Rack env, never from the
+# host's token model: FeatureMachine::Auth::Bearer (or the host's own
+# middleware) has already put a credential at FeatureMachine::ENV_KEY. The
+# prose in 401/403 bodies comes from FeatureMachine.config.
+#
+# The parent is config.api_parent_controller (ActionController::API by
+# default). A host base that already renders errors its own way (render_error,
+# not-found and missing-parameter handling) keeps it; the fallbacks below only
+# fill in what the parent lacks, so a fresh host's API works with no base of
+# its own.
+class Api::FeatureMachine::BaseController < FeatureMachine.config.api_parent_controller.constantize
+  inherited_private = ->(name) { private_method_defined?(name) || method_defined?(name) }
+
+  unless inherited_private.(:render_error)
+    rescue_from ActiveRecord::RecordNotFound do
+      render_error(status: :not_found, error: "Not found", code: "not_found",
+                   resolution: "Verify the resource id belongs to the authenticated user.")
+    end
+    rescue_from ActionController::ParameterMissing do |exception|
+      render_error(status: :bad_request, error: exception.message, code: "parameter_missing",
+                   resolution: "Include the required parameter in the request body.")
+    end
+  end
+
+  private
+
+  # Engine-owned names: a host base's own current_user or current_credential
+  # is left alone, and never stands in for the engine's.
+  attr_reader :api_user, :api_credential
+
+  unless inherited_private.(:render_error)
+    def render_error(status:, error:, code:, resolution: nil, errors: nil)
+      body = { error: error, code: code }
+      body[:resolution] = resolution if resolution
+      body[:errors] = errors if errors
+      render json: body, status: status
+    end
+  end
+
+  # Reads need `read`, writes need `write`; the work-item hand-off overrides
+  # it with `maintainer`.
+  unless inherited_private.(:required_scope)
+    def required_scope
+      request.get? || request.head? ? ::FeatureMachine::READ : ::FeatureMachine::WRITE
+    end
+  end
+
+  def authenticate_user_with_token
+    @api_credential = request.env[::FeatureMachine::ENV_KEY]
+    @api_user = @api_credential&.user
+    return render_unauthenticated unless @api_user
+    return render_session_write_forbidden if session_credential? && !(request.get? || request.head?)
+
+    enforce_scope
+  end
+
+  # The engine's rule, not the credential's: for `maintainer`, the host's admin
+  # predicate must agree (FeatureMachine::Auth.allows?).
+  def enforce_scope
+    return if ::FeatureMachine::Auth.allows?(api_credential, required_scope)
+
+    response.headers["WWW-Authenticate"] =
+      %(Bearer realm="#{feature_machine_config.product_name}", error="insufficient_scope", scope="#{required_scope}")
+    render_error(
+      status: :forbidden,
+      error: "Token lacks the #{required_scope} scope",
+      code: "insufficient_scope",
+      resolution: "This endpoint requires a token with the `#{required_scope}` scope.#{create_token_hint}"
+    )
+  end
+
+  def render_unauthenticated
+    config = feature_machine_config
+    response.headers["WWW-Authenticate"] = [
+      %(Bearer realm="#{config.product_name}", error="invalid_token", error_description="Missing or invalid bearer token."),
+      (%(resource="#{config.protected_resource_url}") if config.protected_resource_url)
+    ].compact.join(", ")
+
+    resolution = [
+      "Send Authorization: Bearer <token>.",
+      ("Humans create tokens at #{config.token_help_url}." if config.token_help_url),
+      ("See #{config.protected_resource_url} for protected-resource metadata." if config.protected_resource_url)
+    ].compact.join(" ")
+    render_error(status: :unauthorized, error: "Unauthorized", code: "unauthorized", resolution: resolution)
+  end
+
+  # A browser session may read through the API; writes take a bearer token,
+  # so a cross-site form can never act on a signed-in user's behalf here.
+  def render_session_write_forbidden
+    render_error(
+      status: :forbidden,
+      error: "Writes need a bearer token",
+      code: "session_write_forbidden",
+      resolution: "This request is authenticated by your browser session, which the API accepts for reads only. Send Authorization: Bearer <token> to write.#{create_token_hint}"
+    )
+  end
+
+  def session_credential?
+    api_credential.respond_to?(:session?) && api_credential.session?
+  end
+
+  def create_token_hint
+    feature_machine_config.token_help_url ? " Create one at #{feature_machine_config.token_help_url}." : ""
+  end
+
+  def feature_machine_config
+    ::FeatureMachine.config
+  end
+end

data/app/controllers/api/feature_machine/bug_reports_controller.rb

@@ -0,0 +1,32 @@
+# Agents report bugs for the user who handed them a token, and follow that
+# user's own reports.
+class Api::FeatureMachine::BugReportsController < Api::FeatureMachine::BaseController
+  before_action :authenticate_user_with_token
+
+  def index
+    @feature_requests = ::FeatureMachine::Request.owned_by(api_user).bug.includes(:user, :work_item).newest_first
+    render "api/feature_machine/feature_requests/index"
+  end
+
+  def create
+    @feature_request = ::FeatureMachine::Request.owned_by(api_user).bug.build(bug_report_params)
+
+    if @feature_request.save
+      render "api/feature_machine/feature_requests/show", status: :created
+    else
+      render_error(
+        status: :unprocessable_entity,
+        error: "Validation failed",
+        code: "validation_failed",
+        errors: @feature_request.errors.full_messages,
+        resolution: "Title is required (8-120 characters). Description is optional, up to 2000 characters."
+      )
+    end
+  end
+
+  private
+
+  def bug_report_params
+    params.require(:bug_report).permit(:title, :description)
+  end
+end

data/app/controllers/api/feature_machine/feature_requests_controller.rb

@@ -0,0 +1,31 @@
+# Agents file feature requests for the user who handed them a token, and
+# follow that user's own requests. No one reads anyone else's.
+class Api::FeatureMachine::FeatureRequestsController < Api::FeatureMachine::BaseController
+  before_action :authenticate_user_with_token
+
+  def index
+    @feature_requests = ::FeatureMachine::Request.owned_by(api_user).feature.includes(:user, :work_item).newest_first
+  end
+
+  def create
+    @feature_request = ::FeatureMachine::Request.owned_by(api_user).feature.build(feature_request_params)
+
+    if @feature_request.save
+      render :show, status: :created
+    else
+      render_error(
+        status: :unprocessable_entity,
+        error: "Validation failed",
+        code: "validation_failed",
+        errors: @feature_request.errors.full_messages,
+        resolution: "Title is required (8-120 characters). Description is optional, up to 2000 characters."
+      )
+    end
+  end
+
+  private
+
+  def feature_request_params
+    params.require(:feature_request).permit(:title, :description)
+  end
+end

data/app/controllers/api/feature_machine/maintainer/feature_requests_controller.rb

@@ -0,0 +1,28 @@
+# The triage inbox as a maintainer's agent sees it: every user's requests and
+# bug reports, so an agent can pull them into whatever tracker the maintainer
+# triages from. Read-only on purpose. Bucketing a request into a work item,
+# or declining it, stays with a human in /admin.
+class Api::FeatureMachine::Maintainer::FeatureRequestsController < Api::FeatureMachine::BaseController
+  before_action :authenticate_user_with_token
+
+  # `untriaged` is the inbox: requested, not yet bucketed into a work item.
+  FILTERS = (%w[untriaged] + ::FeatureMachine::Request.statuses.keys).freeze
+
+  def index
+    filter = params[:status].presence || "untriaged"
+    unless FILTERS.include?(filter)
+      return render_error(status: :unprocessable_entity, error: "Unknown status", code: "validation_failed",
+                          resolution: "status must be one of: #{FILTERS.join(', ')}.")
+    end
+
+    scope = filter == "untriaged" ? ::FeatureMachine::Request.untriaged : ::FeatureMachine::Request.where(status: filter)
+    @feature_requests = scope.includes(:user, :work_item).oldest_first
+    @feature_requests = @feature_requests.where(kind: params[:kind]) if ::FeatureMachine::Request.kinds.key?(params[:kind].to_s)
+  end
+
+  private
+
+  def required_scope
+    ::FeatureMachine::MAINTAINER
+  end
+end

data/app/controllers/api/feature_machine/roadmaps_controller.rb

@@ -0,0 +1,9 @@
+# The roadmap and changelog for a signed-up user's agent. Any `read` token
+# works; there is no anonymous version.
+class Api::FeatureMachine::RoadmapsController < Api::FeatureMachine::BaseController
+  before_action :authenticate_user_with_token
+
+  def show
+    @roadmap = ::FeatureMachine::Roadmap.new
+  end
+end

data/app/controllers/api/feature_machine/work_items_controller.rb

@@ -0,0 +1,56 @@
+# The hand-off surface for a maintainer's agents: read approved work items
+# with their full spec, pick one up, and report progress. Drafts and declined
+# items are invisible here, and nothing about triage (forming, speccing,
+# approving, declining) is reachable: that stays with a human in /admin.
+class Api::FeatureMachine::WorkItemsController < Api::FeatureMachine::BaseController
+  before_action :authenticate_user_with_token
+  before_action :set_work_item, only: %i[show update]
+
+  rescue_from ::FeatureMachine::WorkItem::InvalidTransition, with: :render_invalid_transition
+
+  STATUSES = ::FeatureMachine::WorkItem::MAINTAINER_STATUSES
+
+  # Defaults to the pickup queue: planned work, oldest first.
+  def index
+    status = params[:status].presence || "planned"
+    unless STATUSES.include?(status)
+      return render_error(status: :unprocessable_entity, error: "Unknown status", code: "validation_failed",
+                          resolution: "status must be one of: #{STATUSES.join(', ')}.")
+    end
+
+    @work_items = ::FeatureMachine::WorkItem.where(status: status).includes(feature_requests: :user).order(:created_at)
+  end
+
+  def show
+  end
+
+  # Only `status`, `progress_note` and `pull_request_url`. The spec is the
+  # human's; an agent that disagrees with it says so in the progress note.
+  # Sending the status an item already has is a conflict, not a no-op: that is
+  # what stops a second agent picking up work someone already has. To add a
+  # note or a pull request, send only that.
+  def update
+    attributes = params.require(:work_item).permit(:status, :progress_note, :pull_request_url)
+    changes = attributes.slice(:progress_note, :pull_request_url)
+    attributes[:status].present? ? @work_item.agent_transition!(attributes[:status], changes) : @work_item.update!(changes)
+    render :show
+  rescue ActiveRecord::RecordInvalid => e
+    render_error(status: :unprocessable_entity, error: "Validation failed", code: "validation_failed", errors: e.record.errors.full_messages,
+                 resolution: "Asking for review needs `pull_request_url`: a GitHub pull request URL.")
+  end
+
+  private
+
+  def required_scope
+    ::FeatureMachine::MAINTAINER
+  end
+
+  def set_work_item
+    @work_item = ::FeatureMachine::WorkItem.where(status: STATUSES).find(params[:id])
+  end
+
+  def render_invalid_transition(exception)
+    render_error(status: :conflict, error: exception.message, code: "invalid_transition",
+                 resolution: "Re-read the work item: another agent may have picked it up, or it may already be shipped.")
+  end
+end

data/app/controllers/concerns/feature_machine/current_user.rb

@@ -0,0 +1,28 @@
+module FeatureMachine
+  # Who is asking, by the host's own answer (config.current_user), never by a
+  # current_user method the host may not define. Pages need a signed-in user:
+  # when the host's own filters let a signed-out request through, it goes to
+  # config.sign_in_path, or gets a 401 if the host has none.
+  module CurrentUser
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :feature_machine_user
+    end
+
+    private
+
+    def feature_machine_user
+      return @feature_machine_user if defined?(@feature_machine_user)
+
+      @feature_machine_user = FeatureMachine.config.user_for(request)
+    end
+
+    def require_feature_machine_user
+      return if feature_machine_user
+
+      path = FeatureMachine.config.sign_in_path&.call(self)
+      path ? redirect_to(path) : head(:unauthorized)
+    end
+  end
+end

data/app/controllers/concerns/feature_machine/engine_layout.rb

@@ -0,0 +1,12 @@
+module FeatureMachine
+  # Engine pages render through FeatureMachine.config.layout. Rails treats a
+  # nil from the proc as "no opinion", so the host's inherited layout applies
+  # and engine pages look like the rest of the host's.
+  module EngineLayout
+    extend ActiveSupport::Concern
+
+    included do
+      layout -> { FeatureMachine.config.layout }
+    end
+  end
+end

data/app/controllers/feature_machine/admin/attachments_controller.rb

@@ -0,0 +1,17 @@
+# Attaches untriaged requests (typically a whole triage bucket) to an
+# existing work item.
+class FeatureMachine::Admin::AttachmentsController < FeatureMachine::Admin::BaseController
+  def create
+    return redirect_to(admin_triage_path, alert: "Choose a work item to add those requests to.") if params[:work_item_id].blank?
+
+    # Only items still in play: attaching to a shipped or declined one would
+    # stamp the requests with that outcome straight away.
+    work_item = ::FeatureMachine::WorkItem.active.find(params[:work_item_id])
+    requests = ::FeatureMachine::Request.untriaged.where(id: params[:request_ids]).to_a
+    ::FeatureMachine::Request.transaction do
+      requests.each { |request| request.update!(work_item: work_item) }
+    end
+
+    redirect_to admin_triage_path, notice: "#{helpers.pluralize(requests.size, 'request')} attached to \"#{work_item.title}\"."
+  end
+end