@noodleseed/agent-kit 0.91.0 → 0.92.0

package/skills/codex/wrapping-existing-applications/references/wrap-existing-app.md

@@ -0,0 +1,65 @@
+# Outcome
+
+Produce a sanitized, repository-grounded plan for wrapping an existing application with a focused Noodle Seed MCP server. Discovery is read-only: present the capability map and implementation phases in the conversation, then stop before writing a plan or source file until the user explicitly authorizes that local mutation and repository.
+
+## Contents
+
+- Use when
+- Do not use when
+- Required inputs
+- Workflow
+- Verification evidence
+- Recovery paths
+- Stop conditions
+
+## Use when
+
+- An existing web application has internal HTTP handlers, framework-owned server calls, or inline database-backed logic but no stable, usable public API or specification.
+- The user wants a decision-complete integration plan before changing the application or Noodle project.
+
+## Do not use when
+
+- Only when all four API-evidence inputs exist—an API base URL, authentication scheme, representative safe read, and observed response—use the API-connection route. If any input is missing, stale, inaccessible, undocumented-only, or otherwise unusable, remain on the existing-application planning route.
+- The request is already-approved implementation, failure diagnosis, deployment, publication, or a host-visible App outcome; use that owning route.
+- Source access is unavailable and the user expects a repository-grounded plan. Return the bounded evidence checklist instead of inventing routes or schemas.
+
+## Required inputs
+
+Confirm the repository or repositories in scope, the user jobs to expose, the requested stopping point, which identity provider authenticates end users, whether callers are the owner's staff or the application's customers, and whether the relevant deployment has one static preconfigured downstream origin.
+
+Never read or print `.env` / `.env.noodle` values, credential stores, browser cookies, production records, secret-bearing logs, or customer payloads. Inspect source, route declarations, authentication middleware, tests, and non-secret configuration declarations only. Record sanitized capability descriptions and source locations, never copied customer code or data.
+
+## Workflow
+
+1. **Establish authority.** Name every repository in scope and whether the user requested discovery, a draft plan, local implementation, or a higher evidence level. Discovery alone authorizes no file or hosted mutation.
+2. **Ask identity first.** Before connector design, ask which identity provider authenticates end users and whether MCP callers are staff or customers. Separate **inbound MCP identity** from **downstream application authorization**. A supported provider can simplify inbound configuration; it does not automatically authorize downstream calls. An application session is not itself an inbound customer identity. Without a standards-based issuer, current production choices are the staff/service-credential path or a customer-built standards-based authorization server; the generic identity bridge is demand-gated and not shipped.
+3. **Choose downstream authorization honestly.** A shared service credential provides attribution, not per-user authorization, and should be least-privilege. Once Noodle has a verified caller identity, a delegated path requires one compatible token endpoint, whether existing or newly added, plus bearer acceptance in the relevant middleware. That endpoint does not solve the inbound session-only identity gap. Logic without a stable HTTP entry point may also need a thin HTTP handler over the existing business function.
+4. **Choose routing.** Use one static `http` connector with one static preconfigured downstream origin so the same server can serve embedded and external MCP clients. The canonical no-API path is a small application-owned integration layer with stable HTTPS handlers over existing business functions. Any downstream origin receiving a service or delegated credential must use HTTPS. Reject redirects for requests carrying service or delegated credentials; require the final HTTPS origin to be configured directly. If the application requires multi-origin routing or has no stable HTTP origin, stop, report a blocker, and hand off to the existing owning routing workflow. Browser input, model text, page context, tool arguments, and caller input cannot select an origin.
+5. **Map jobs, not routes.** For each user job record a sanitized source location, current HTTP/auth boundary, read or action effect, route-adapter need, proposed intent-shaped tool, minimal typed result, confirmation need, and verification evidence. Treat five to twelve tools as a normal budget, not a minimum; a smaller product should ship fewer. Design intent tools, not one tool per internal route.
+6. **Reject unstable seams.** Do not call an unstable server-call protocol whose identifier or serialization changes across builds. Never use direct database access, including ORM or SQL; it bypasses application authorization and business rules. Do not log in and copy a browser session into the runtime; copying a browser session or its credentials into the runtime is prohibited. Do not treat a service credential as per-user authorization. Propose a narrow application-owned HTTP handler instead.
+7. **Separate implementation ownership.** Produce an existing-application phase for handlers/auth/tests, a Noodle-project phase for TypeScript connector/tools/fakes/tests, and a cross-surface verification phase. If repositories differ, create separate repository-scoped plans and approval boundaries.
+8. **Present and stop.** Show the capability map, identity/routing decision, minimum honest application changes, rejected alternatives, test matrix, risks, and phases in the conversation. A design approval is review only. Local implementation requires an explicit “proceed” for the named repository. Local implementation approval does not authorize hosted configuration, live writes, deployment, publication, or issue-state changes; those require their own authority.
+9. **Hand off approved work.** Once a decision-complete local plan is explicitly authorized, persist it when repository workflow requires and hand it to `executing-noodle-plans`. Use the existing server-authoring and API-connection playbooks for implementation and real-output evidence; do not add another task loop here.
+
+## Verification evidence
+
+- **Discovery:** repository instructions, stable HTTP boundaries, auth middleware, and tests were inspected read-only without secret values or copied customer data.
+- **Decision:** inbound identity, downstream authorization, one static preconfigured downstream origin, and required application changes are explicit rather than inferred.
+- **Product:** each proposed tool maps to a user job, typed result, effect, and backing operation within the stated surface budget.
+- **Plan:** application, Noodle, and cross-surface phases name files or subsystems, tests, blockers, approval boundaries, and the first unproven layer.
+- **Conformance boundary:** a later representative safe `noodle tools call` can prove one observed mapping; it does not prove general schema conformance. A dedicated conformance feature is separate.
+
+## Recovery paths
+
+- Unknown identity provider or caller population: stop before choosing customer auth or delegated credentials and ask that one question.
+- No source access: provide the exact route/auth/test evidence checklist and report that no repository-grounded plan was produced.
+- Stable origin but no safe stable HTTP boundary: plan the smallest application-owned stable HTTPS adapter over existing business functions instead of calling a private server protocol.
+- A multi-origin requirement or no stable HTTP origin: stop, report the routing blocker, and hand off to the existing owning routing workflow; browser, model, tool, and caller input cannot select an origin.
+- Missing safe live verification input or working credential: leave that evidence explicitly unproven and name the exact prerequisite. A missing reachable service or action sandbox is handled the same way.
+
+## Stop conditions
+
+- Stop after presenting the draft capability map and plan until the user explicitly approves the next local mutation and repository.
+- Stop before live writes, hosted configuration, deployment, publication, or issue-state mutation without separate explicit authorization.
+- Stop blocked and hand off to the existing owning routing workflow only when the application requires multi-origin routing or has no stable HTTP origin.
+- This workflow does not add an importer, generate manifests or IR, or implement live schema probing, inference, or diffing.