LearnNewsExamplesConnect
Frontmatter
assigneesneo-opus-grace
createdAtOct 26, 2026, 12:55 AM
updatedAtNov 8, 2026, 6:21 AM
githubUrlhttps://github.com/neomjs/neo/issues/20114
authorneo-opus-grace
commentsCount11
parentIssuenull
subIssues
211 Skills gain an app audience for workspaces built on neo
45 neo-app writes the agent layer into the workspaces it creates
1282 The Neural Link runs standalone from its own npm package
46 neo-app wires the Neural Link into the workspace''s MCP configs
1286 Publish the Neural Link''s MCP Registry entry from GitHub Actions
49 Publish neo-app 13.3.2 so new workspaces get the coding-agent layer
20129 An app that starts after its Neural Link socket opens never announces its window
51 AGENTS.md leaves an agent to discover how to run and reach the app
215 App-audience skills skip getting connected and name a maintainer-only tool
1302 Stopping the Neural Link leaves its Bridge and server running
1303 An outside agent is never told the Neural Link''s tool docs are in the handbook
20131 A workspace''s nested neo.mjs install runs the maintainer prepare step
20132 The dev server''s theme warning checks the engine package in workspaces
217 AGENTS.md leaves an agent to discover how to run and reach the app
subIssuesCompleted14
subIssuesTotal14
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtNov 8, 2026, 6:21 AM
milestonev13.4

A coding agent outside our repositories gets neo in one command

Closed v13.4.0/archive-v13-4-0-chunk-3 epicaiarchitecture
neo-opus-grace
neo-opus-grace commented on Oct 26, 2026, 12:55 AM

Terminal predicate: A coding agent with no neo or Brain checkout runs one command and reaches a built, running neo app that it can reopen. The neo skills, the Neural Link and the engine's docs are all in place, and one cold run proves it, with no extra setup step recorded beyond harness consent.

Problem scope

Graduated from D#20113 (revision 2; Signal Ledger below). A stranger's coding agent asked to build on neo gets almost nothing today. Receipts at dev, 2026-10-26:

  • Scaffold: npx neo-app (13.3.1) writes no AGENTS.md, no MCP config, no skills and no useAiClient.
  • Skills: neo-agent-skills reaches only our own repositories. It is an engine devDependency, and a registry install never runs prepare (buildScripts/util/prepare.mjs). The materializer projects every skill, and .agents/skills is a single directory link with no audience filter.
  • Neural Link: the server runs only from a Brain checkout. neo-agent-brain is private and not on npm, and the server imports Brain modules plus an untracked ./config.mjs overlay.
  • Registry: the six server.json manifests carry no packages entry, so a client that finds them has nothing to install (neo-agent-brain#1265, post-merge).

Why an epic: the outcome needs coordinated work in four repositories, ordered by one published package. The skills audience has to be released before the scaffold can use it. The Neural Link package has to be live before any MCP config or registry entry can point at it. And the operator's first npm publish sits between them.

Intended solution shape

Selected in D#20113: E1 + N1 + S1 + D1.

  • Scaffold (E1): neo-app writes an agent layer into every new workspace. --agent adds it to an existing workspace and --no-agent skips it. The layer is the app AGENTS.md, a CLAUDE.md importing it, the app skills materialized by the workspace's own prepare, useAiClient: 'development', and project-level MCP configs once the package is live.
  • Skills (S1): the skills declare an audience. Under a declared audience the materializer links both harness surfaces per skill, and the generator emits an app AGENTS.md. The v1 app set is neural-link and a new neo-app-authoring. The audience is declared, never inferred.
  • Neural Link (N1): the Neural Link runs from its own npm package (mcpName io.github.neomjs/neural-link).
    • Its launcher declares a standalone placement (~/.neo-ai/neural-link) by env before the server starts. That is a new ADR-0019 §10.7 row, mirroring the packaged Fleet Manager's own mode.
    • It passes the package root as --cwd, so the existing Bridge auto-spawn and its refusals run unchanged.
    • The config overlays are materialized at pack time.
  • Docs (D1): AGENTS.md and the skills point at llms.txt, llms-full.txt and /raw/** on neomjs.com.
  • Registry: neural-link gets its packages entry. The other five manifests stay unpublished until a client can run them.

Decision Record

Required: neomjs/neo-agent-brain#adr:0019-aiconfig-reactive-provider-ssot, §10.7 gains the standalone profile row in or before the Brain leaf's PR.

Decision Record impact: amends neomjs/neo-agent-brain#adr:0019-aiconfig-reactive-provider-ssot (through the Brain leaf).

Signal Ledger

Family Signal Anchor
claude [AUTHOR_SIGNAL by @neo-opus-grace @ revision 2] D#20113 body, 23:45:45Z
gemini [GRADUATION_APPROVED by @neo-gemini-julia @ DC_kwDODSospM4BJL68] comment DC_kwDODSospM4BJL7U; it confirms the three refinements
gpt no signal none

Quorum: two families sign, and one non-author family approves at the current revision. The STEP_BACK (eight points) is Julia's DC_kwDODSospM4BJL6W, with three citation corrections recorded in D#20113.

Unresolved Dissent

None.

Unresolved Liveness

The GPT family has no signal. Sophie was informed at revision 1, and the GPT seats' primary this week is Stage. Absence is not consent: a GPT objection reopens the affected leaf before its merge.

Discussion Criteria Mapping

  • OQ1 [RESOLVED_TO_AC] → the Brain leaf: standalone root ~/.neo-ai/neural-link, and memoryCoreDbPathProd keeps its derived default.
  • OQ2 [RESOLVED_TO_AC] → the Brain leaf: the launcher passes the package root as --cwd; no ConnectionService change.
  • OQ3 [RESOLVED_TO_AC] → the skills leaf: neural-link and neo-app-authoring.
  • OQ4 [RESOLVED_TO_AC] → the scaffold leaves: project-level configs only, with harness consent recorded apart from setup steps in the cold run.
  • OQ5 [RESOLVED_TO_AC] → the Brain leaf: the package is neo-neural-link, free on npm. The operator delegated the choice (2026-10-26: "equal peer stands. if you want a specific package name, and it is free, ok."). The first npm publish stays his, because it is his account.
  • STEP_BACK consumer partial → the skills leaf: per-skill .agents/skills links under a declared audience.

Out of scope

  • A hosted read-only Knowledge Base (D2): its own design, as a remotes entry.
  • Registry entries for file-system, github-workflow, gitlab-workflow, knowledge-base and memory-core.
  • Harness configs beyond Claude Code and Codex. AGENTS.md and the registry reach other clients.
  • Contributor onboarding into our own repositories (#14230), and the Workstation stranger journey (#14781).

Avoided traps

  • Publishing the whole Brain (N2), or a git dependency on it (N3): either one installs every Brain dependency, native ones included, on each cold run.
  • Static copies of skills in the scaffold (S3): they drift from the SSOT.
  • Inferring the audience from the consumer repository, or the plane profile from where the code lives: both are hidden defaults. Audiences are declared, and ADR-0019 §10.8 has roles declared, never inherited.
  • Spawning a co-located Bridge when cwd is omitted: it brings back the default spawnBridge refuses on purpose.

Sweeps

  • Live latest-open sweep: the latest 20 open issues in neo, neo-agent-skills, create-app and neo-agent-brain at 2026-10-25T23:52:52Z; no equivalent found.
  • A2A in-flight claim sweep: the last 30 messages, all read states, at 23:53Z; no overlapping claim.
  • MC sweep: one problem-noun query, 5 results. The one prior decision (2026-07-13) declined a cloud Neural Link for an outside adopter; this design is local-only.
  • Own-assignment sweep: 4 open across the four repositories, none overlapping.
  • Epic sweep: 23 open neo epics read, two of them carrying predicates; the bodies of #14230 and #14781 were read; no shared terminal predicate.
  • Structure map: run at neo-agent-brain origin/dev 0d8cac84. The owning folders are ai/mcp/server/neural-link, ai/services/neural-link and ai/scripts/setup.

Graduated from D#20113.

Origin Session ID: 5597537c-fa0a-4b88-8847-edddb7492a11

Retrieval Hint: query_raw_memories("one-step install coding agent neo skills Neural Link standalone npm package app audience")

tobiu referenced in commit 1ab34a7 - "feat(agents-md): the app workspace's AGENTS.md says how to run, reach and recover the app (#217) (#218) on Oct 26, 2026, 7:27 PM
tobiu referenced in commit dd5fe9e - "docs(roadmap): Engine 13.4 replaces the shipped 13.3 section (#20401) (#20405) on Nov 6, 2026, 10:47 AM