What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	feat(ai): add ticket-create skill (#10104)
author	tobiu
state	Merged
createdAt	Apr 20, 2026, 1:40 AM
updatedAt	Apr 20, 2026, 1:57 AM
closedAt	Apr 20, 2026, 1:57 AM
mergedAt	Apr 20, 2026, 1:57 AM
branches	`dev` ← `feat/10104-ticket-create-skill`
url	https://github.com/neomjs/neo/pull/10116

Merged

tobiu commented on Apr 20, 2026, 1:40 AM

Summary

Adds .agent/skills/ticket-create/ — the creation-side dual of ticket-intake. Centralizes issue-creation discipline that was previously fragmented across 4 surfaces (create_issue MCP tool description, ticket-intake skill (consumption-only), AGENTS_STARTUP.md §9, tribal knowledge). Every new session previously re-derived the rules from precedent; the [enhancement]-prefix anti-pattern spreading across multiple tickets is the direct evidence.

What's New

File	Purpose
`.agent/skills/ticket-create/SKILL.md`	Trigger description; mirrors `ticket-intake/SKILL.md` structure
`.agent/skills/ticket-create/references/ticket-create-workflow.md`	Canonical workflow: duplicate sweep → challenge chain → title hygiene → label rules → Fat Ticket body → visible proposal → linkage → anti-patterns → escalation-to-discussion
`.agent/skills/ticket-create/assets/ticket-proposal-template.md`	Chat-dump format for the mandatory visible-proposal protocol

What's Shrunk

File	Before → After
`AGENTS_STARTUP.md §9`	21 lines (9 numbered items) → 12 lines (5 paragraphs with skill pointers)
`ai/mcp/server/github-workflow/openapi.yaml` `create_issue.description`	~27 lines (CRITICAL PROTOCOL + MANDATORY WORKFLOW + STRICT LABELING + Post-Creation) → 5 lines (skill pointer + minimum tool guidance)

Rationale for yaml shrink: tool descriptions ride in every agent's tool list on every session boot — length is not free. Companion in-flight work on reducing default tool descriptions + introducing a getDescription tool makes the minimum-viable description pattern the right trajectory now. Skill files are the right substrate for long-form protocol.

Rationale for §9 shrink: AGENTS_STARTUP.md is approaching context-cap limits for some harnesses (Antigravity). Migrating the creation-specific content to the skill while keeping §9.7 handoff context inline reduces startup cost for every session.

What's Added to Learn Docs

learn/agentos/ProgressiveDisclosureSkills.md:

New ### 4. ticket-create (The Creation Gate) section describing the skill's four enforcement surfaces
New ticket-create row in the Skill Inventory table

Mermaid lifecycle diagram left unchanged — ticket-create is orthogonal to the execution flow (fires during any turn where an agent decides to file a new ticket), not a pre-sequel to ticket-intake.

Architectural Anchor Points

The skill codifies patterns observed and debugged across recent sessions:

Title hygiene: [enhancement] / [bug] / [epic] prefix duplicates label taxonomy. Memory: feedback_no_title_prefix_duplicating_labels.md. Evidence: prior session's #10085/#10086/#10087/#10103 all carried the prefix, propagated via precedent-following despite the feedback memory existing.
Architectural Reality section: the §9.6 body requirement was preserved in the skill's Fat Ticket structure — originally omitted from the first draft, caught during review of this PR's own scope.
Five-stage challenge chain: premise → prescription → substrate → consumer → service-boundary — codified at creation time (not just intake). Memories: feedback_challenge_prescribed_fixes, feedback_config_service_boundary, feedback_observability_consumer_identity, feedback_audit_subsystem_guides_before_architectural_claims.
Duplicate sweep command: grep on resources/content/issues/, issue-archive/, discussions/ plus ask_knowledge_base(type='ticket') as primary. AGENTS_STARTUP §9 only mentioned issues + discussions; skill adds issue-archive/ coverage explicitly.
Visible proposal protocol: mandatory chat-dump before create_issue fires. Moved from tool description to skill so the full template with placeholders can live there.

Test Deferred

AC item #6 ("a representative test: generate a new test ticket through the skill, verify it hits all the hygiene rules") deferred per commander decision. Skill is prescriptive documentation; a file-parse self-consistency test has marginal value relative to the file-count + review burden. If anti-patterns regress in future tickets, the right enforcement is either a CI lint (hook reading the markdown template against new tickets) or simply catching it in pr-review.

Test Plan

Skill files created with proper frontmatter (SKILL.md has name, description, triggers)
Workflow reference structured with numbered sections matching the ticket's AC list
Template file provides visible-proposal format with placeholders
AGENTS_STARTUP.md §9 shrunk; skill-pointer paragraph added; §9.7 handoff context preserved
openapi.yaml create_issue description minimized with skill pointer
toolService.mjs verified — maps tool names to methods only; no description duplication
learn/agentos/ProgressiveDisclosureSkills.md skill inventory + new §4 section added
Post-merge: next agent session's ticket creation should invoke the skill before create_issue — observe organically

Sibling (consumption dual): .agent/skills/ticket-intake/
Origin session: 1db25bbe-f39d-4dcd-bb0e-bc125ce91326 (ticket originator; captured the [enhancement]-prefix anti-pattern observation)
Memory evidence supporting scope: feedback_no_title_prefix_duplicating_labels, feedback_audit_subsystem_guides_before_architectural_claims, feedback_blocker_reserved_for_merge_breaking, feedback_challenge_prescribed_fixes, feedback_memory_before_forensics, + others

Avoided Traps

Inlining discipline in AGENTS_STARTUP §9: rejected — would bloat an already-long startup doc; violates the context-cap constraint user flagged
Inlining discipline in openapi.yaml tool description: rejected — tool descriptions ride in every session's tool list, length penalty compounds; can't include structured examples
Writing a file-parse test: rejected per commander decision — marginal value for a docs-only skill

Resolves #10104

🤖 Generated with Claude Code

tobiu commented on Apr 20, 2026, 1:41 AM

Input from Claude Opus 4.7 (Claude Code):

❋ # PR Review Summary

Status: Approved — ready for human QA

Self-Review Opening: Self-review of #10104. This implementation chose to mirror the sibling ticket-intake skill structure rather than invent a new shape — SKILL.md frontmatter + references/ workflow + assets/ template — because pattern replication is the lowest-cost way for agents to load a mental model. The aggressive shrink of AGENTS_STARTUP.md §9 and the openapi.yaml tool description was made possible by this centralization: both now point at the skill as the single source of truth for creation discipline. Key trade-offs and one in-flight self-correction below.

Self-Review Detection: same persisted-memory blind spot as PRs #10114/#10115 — query_raw_memories('#10104') returned prior tickets' matches via semantic similarity but no literal #10104 hit. Manually overriding to self-review mode based on factual authorship (drafted the 3 skill files + 3 doc updates in this turn).

Tech Debt Radar: skipped. This is a feat(ai) adding a new orthogonal skill, not a framework refactor or architectural shift to existing systems. The new skill lives alongside existing lifecycle skills without touching their internals.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 92 — Faithful mirroring of the ticket-intake skill's three-file structure. Workflow file uses established numbered-section convention. Skill inventory table + §4 section added to ProgressiveDisclosureSkills.md follow the existing pattern for lifecycle skill documentation. Did not touch the mermaid lifecycle diagram — correct call, as ticket-create is orthogonal (creation trigger, not execution sequence).

[CONTENT_COMPLETENESS]: 90 — SKILL.md has full frontmatter (name + description + triggers); workflow covers all 10 sections from the ticket's AC plus one addition (§10 escalate-to-discussion); template has placeholders + label rules footer. Self-correction flagged: first draft of the workflow's Fat Ticket Body Structure section omitted the "Architectural Reality" named section (which AGENTS_STARTUP.md §9.6 mandated and which I've actually been using in all my Fat Tickets this session). Caught during a re-read of the original §9 before the §9 shrink, added as a dedicated section to both the workflow and template. If I'd let that slip, the new skill would have ratified the omission and future tickets would have drifted.

[EXECUTION_QUALITY]: 80 — Docs-only PR; no tests by design per commander decision (AC item #6 deferred with rationale in PR body). Docked for the in-flight omission described above — self-caught but should have been scope-complete on the first pass. No syntactic or structural errors in any file.

[PRODUCTIVITY]: 90 — 5 of 6 AC items met pre-merge; AC #6 (representative test) deferred per commander decision, documented in PR body.

[IMPACT]: 60 — Affects every future agent-authored ticket creation across the swarm. Reduces AGENTS_STARTUP.md startup cost (context-cap relief), reduces openapi.yaml tool-description weight in every session's tool list. Three compounding wins, each modest, combined meaningful.

[COMPLEXITY]: 45 — 3 new files (~186 lines net added) + 3 surface updates across 3 different substrates (startup doc, MCP tool description, learn doc). Multi-surface coordination is the complexity driver, not any single file's shape.

[EFFORT_PROFILE]: Quick Win — high-leverage centralization, modest scope, no code-execution path touched.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #10104

Related Graph Nodes:

Sibling (consumption dual): .agent/skills/ticket-intake/ — structure precedent

Origin session (ticket originator): 1db25bbe-f39d-4dcd-bb0e-bc125ce91326 — captured the [enhancement]-prefix anti-pattern observation that motivated this ticket

Memory evidence behind the scope: feedback_no_title_prefix_duplicating_labels, feedback_audit_subsystem_guides_before_architectural_claims, feedback_blocker_reserved_for_merge_breaking, feedback_challenge_prescribed_fixes, feedback_memory_before_forensics, feedback_config_service_boundary, feedback_observability_consumer_identity

🧠 Graph Ingestion Notes

[RETROSPECTIVE]: Pattern replication as a cognitive-load reducer. The choice to mirror ticket-intake's structure exactly (not "improve" it) is deliberate — agents load a skill's mental model faster when it rhymes with an already-known sibling. The same logic applies inside each skill: using the numbered-section convention from intake means the workflow file is navigable on sight. Resist the temptation to "refactor while migrating" — structural consistency has compounding value across the skill manifest.

[RETROSPECTIVE]: The in-flight "Architectural Reality section was missing" self-correction is a concrete instance of the feedback_audit_subsystem_guides_before_architectural_claims lesson applied backward: re-reading the original §9 source-of-truth before shrinking it caught the omission that would otherwise have persisted into the skill. If I had shrunk §9 first (aggressive delete) without re-reading the numbered subsections, the Architectural Reality requirement would have vanished from the documentation ecosystem entirely. Lesson: when migrating content between substrates, do a named-element audit across both substrates before the delete, not after.

[TOOLING_GAP]: Same Self-Review Detection issue flagged on prior PRs in this session (persisted-memory query misses same-turn authorship). Not re-flagging as a novel finding; the previous review's capture stands.

[KB_GAP]: None. The skill itself is a KB gap closure.

📋 Required Actions

Zero Blockers. Zero Nits.

Post-merge observation (unavoidable): next agent session's ticket creation should invoke the ticket-create skill before create_issue fires. The new openapi.yaml tool description directs them to it. Organic validation — if agents skip the skill anyway, the yaml directive needs strengthening or CI lint enforcement considered as a follow-up.

Optional symmetry improvement (not blocking, not filed): ticket-intake/SKILL.md could add a single sentence pointer to ticket-create in its intro for discoverability parity. Would complete the bidirectional dual framing. Marginal value; skippable.

Handing off to human QA per §5 of pull-request-workflow.md. DO NOT auto-merge.