Developer Experience¶
Developer experience, project memory, and process ergonomics.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
As a developer, I want to have project knowledge automatically maintained, so that new Copilot sessions have full context. Acceptance Scenarios:
|
As a developer, I want to have agents present choices using VS Code’s native selection menus (quick-pick UI) instead of plain-text questions, so that I can respond efficiently with a single click and have a consistent interaction experience across all agents. Acceptance Scenarios:
|
As a developer working with ubFlow, I want to use consistent, well-integrated MCP tools for all Sphinx-Needs queries, so that I have a single, reliable approach without confusion between legacy scripts and modern tools. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Description: ubFlow SHALL provide a memory agent that maintains the project’s copilot-instructions.md as the codebase evolves. Rationale: Long-term project memory ensures new Copilot sessions have full context. Acceptance Criteria:
|
Description:
ubFlow agents SHALL use VS Code’s Rationale: Free-text choices require users to type or copy responses, and the presentation varies between agents. Using the native selection menu provides a consistent, single-click interaction pattern across all agents. Acceptance Criteria:
|
Description: ubFlow SHALL provide a mechanism for consolidating reusable interaction patterns into shared skill files that are available to all agents. Rationale: Without consolidation, reusable patterns (like how to present choices) must be duplicated across agent files. Skill files define the pattern once and make it available to all agents through a single reference. Acceptance Criteria:
|
Description: ubFlow documentation SHALL use ubCode MCP Server tools exclusively for all Sphinx-Needs traceability query examples, removing all references to the legacy get_need_links.py Python script. Rationale: Documentation is the primary way developers learn ubFlow patterns. Consistent, accurate examples using MCP tools prevent confusion and ensure better developer experience. Acceptance Criteria:
Verification Method:
|
Description: ubFlow agent definition files SHALL use ubCode MCP Server tools exclusively for all Sphinx-Needs traceability operations, removing all references to executing the legacy get_need_links.py Python script via terminal commands. Rationale: Agents are AI-driven and benefit from direct MCP tool integration. Using MCP tools instead of terminal commands provides better error handling, type safety, and integration with the VS Code environment. Acceptance Criteria:
Verification Method:
|
Level 2: Design (HOW)¶
Memory Agent¶
Design:
The Memory Agent follows a three-step process to keep
Core Principle: If an agent can learn it by reading an existing file, don’t put it in copilot-instructions.md. The file contains only what agents cannot easily discover from the codebase. Step 1 — Gather Current State:
Step 2 — Identify Gaps: Compare documented state vs reality. Focus on:
Before adding anything, ask: “Can the agent discover this by reading an existing file?” — if yes, don’t add (at most add a one-line pointer). Step 3 — Apply Updates: Add, modify, or remove sections. Commit the change. Invocation: Invoked after verify in the change workflow. Hands off to change (for another change) or release (to bundle into a release). File: |
Design: The Memory Agent decides what belongs in copilot-instructions.md using a single criterion: discoverability. Include (not discoverable from code):
Exclude (discoverable from existing files):
Rule of thumb: If it changes every commit, it shouldn’t be documented. If another file already says it, link don’t copy. |
Design:
The Memory Agent maintains a fixed set of sections in
Target Structure: # [Project Name] - Copilot Instructions
## Project Overview — 3-5 lines, version
## Tech Stack — bullet list, no versions
## Project Structure — directory tree (no per-file listings)
## Specification Hierarchy — 3-level diagram with prefixes
## Agent System — table: agent → purpose
## Sphinx-Needs Conventions — ID prefixes, theme abbreviations
## Development Commands — build + query commands only
## Development Workflow — agent chain diagram, one-liners
## Patterns & Conventions — file organization, file naming, authoring
## Agent Interaction — skill file activation reference
Size target: ~150–180 lines. If it grows past 200, something should be cut. Location: Update Frequency: After each verify pass or on-demand when significant structural changes occur. |
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Consistent Agent Interaction via Selection Menus |
implemented |
high |
|
Consistent MCP Tool Usage for Traceability |
draft |
high |
|
Maintain Project Memory |
implemented |
high |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
Agent Selection Menus for User Choices |
implemented |
devexperience; agent; ux; developer-experience |
|
Shared Skill Files for Agent Patterns |
implemented |
devexperience; agent; ux; developer-experience; skills |
|
Project Memory Agent |
implemented |
devexperience; agent; memory |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
Memory Content Rules |
implemented |
||
copilot-instructions.md Structure |
implemented |
||
Memory Update Process |
implemented |