usm/agent-feedback [built]
Agent feedback protocol — teaches AI agents a consistent, configurable way to surface bugs and improvements, governed by a schema-driven policy set up at init time, rendered into every agent-facing rules file, and backed by a usm_report_feedback MCP write tool that records structured .usm/feedback entries. Stops agents inventing ad-hoc bug-tracking files.
Status: built
Intent
Agents using USM currently improvise when they discover issues — one agent autonomously created a root-level bugs.md because no canonical protocol exists. There is no taught, configurable behaviour for how an agent should report a bug or suggest an improvement. This feature adds (1) a system.feedback policy block to the v1 schema with three modes — human-gate (default, surface in conversation and ask), direct-to-feedback (write structured entries to .usm/feedback), and direct-to-github (file a real issue via gh); (2) interactive prompts in usm init / scan that ask whether the dev agent has GitHub auth and which policy to use; (3) a shared Feedback Protocol block generated into all four rules files (AGENTS.md, CLAUDE.md, .cursor/rules/usm.mdc, copilot-instructions.md) that renders the project's configured policy and forbids ad-hoc tracking files; and (4) a usm_report_feedback MCP write tool that validates and persists structured feedback entries. One source of truth (system.usm feedback policy) drives consistent agent behaviour across the whole ecosystem.
Decisions
default-human-gate
Decision: human-gate is the default policy
Rationale: Matches USM's human-in-the-loop philosophy (ALWAYS show the human first). Prevents noisy autonomous issues and unreviewed files. Projects with confidence and gh auth can opt into direct modes.
feedback-as-first-class-usm-type
Decision: Feedback entries are $type: feedback .usm files in .usm/feedback, not a free-form markdown log
Rationale: Consistent with structured-source-of-truth principle. Validated, queryable via MCP, convertible to features/issues. Avoids the drift that made ad-hoc bugs.md useless.
one-shared-protocol-block
Decision: A single Feedback Protocol block is rendered into all four rules files from one code path
Rationale: Same rationale as the existing WORKFLOW_INSTRUCTIONS — one source, avoids drift between agent tools (Cursor/Claude/Codex/Copilot).
setup-asks-two-questions
Decision: usm init asks exactly two questions: gh auth presence and policy choice
Rationale: Minimal friction. gh_auth gates the direct-to-github option; policy drives everything else. Tracker and feedback_dir have sensible defaults.
mcp-tool-respects-policy
Decision: usm_report_feedback consults system.feedback.policy before writing
Rationale: In human-gate mode the tool returns a draft preview for the human instead of writing, keeping the agent honest even if it ignores the rules file.
Flows
Configure feedback policy at init (setup-feedback-policy)
usm init (and usm scan --enrich) asks the human two questions and persists a system.feedback block
- prompt → Does your dev agent have GitHub auth? (gh CLI authenticated) — sets feedback.github_auth: true|false|unknown
- prompt → How should agents report bugs/improvements? — sets feedback.policy: human-gate (default) | direct-to-feedback | direct-to-github
- write → system.usm feedback block with policy, github_auth, tracker (defaults to identity.repository + /issues), feedback_dir (.usm/feedback)
- validate → system.usm against v1 schema including new feedback block
Agent surfaces an issue following the configured policy (agent-reports-feedback)
When an agent discovers a bug or improvement, its behaviour is governed entirely by system.feedback.policy
- detect → agent encounters a bug, inconsistency, or improvement opportunity
- branch → read system.feedback.policy
- human-gate → describe the issue to the human in conversation and ask whether to record/file it — do NOT write anything without approval
- direct-to-feedback → call usm_report_feedback to write a structured .usm/feedback entry
- direct-to-github → run gh issue create using the bug_report template (only when github_auth is true)
- forbidden → NEVER create ad-hoc tracking files at the repo root (bugs.md, ISSUES.md, TODO-agent.md, etc.)
Render feedback protocol into all rules files (generate-protocol-instructions)
During usm generate, a shared Feedback Protocol block is emitted into every agent-facing file, dynamic to the project policy
- parse → system.usm feedback block (policy, github_auth, tracker, feedback_dir)
- generate → policy-specific instructions — the exact behaviour for the configured mode
- render → shared block into AGENTS.md, CLAUDE.md, .cursor/rules/usm.mdc, .github/copilot-instructions.md
- smart-merge → replace between USM markers, preserve hand-written content
Human reviews collected feedback (human-reviews-feedback)
Feedback entries written to .usm/feedback are reviewable and convertible into issues or features
- list → usm list --type feedback or usm_report_feedback list shows open entries
- triage → human marks status: open -> acknowledged -> resolved | wontfix
- convert → promote a feedback entry into a feature .usm spec or a GitHub issue
Contracts
policy-respected
All generated instructions and the MCP tool must honour the configured system.feedback.policy
Acceptance criteria:
- [ ] human-gate mode instructs the agent to ask the human and forbids autonomous writes
- [ ] direct-to-feedback mode instructs the agent to call usm_report_feedback
- [ ] direct-to-github mode is only offered/emitted when feedback.github_auth is true
no-adhoc-tracking-files
The protocol must explicitly forbid agents from inventing their own bug/issue tracking files
Acceptance criteria:
- [ ] Hard rule present in every rules file: NEVER create ad-hoc tracking files at repo root
- [ ] Canonical feedback location named: .usm/feedback (overridable via feedback_dir)
feedback-schema-validated
Feedback entries are first-class .usm files validated against the schema
Acceptance criteria:
- [ ] $type: feedback recognised by the v1 schema
- [ ] Required fields: kind (bug|improvement|question), severity, summary, status, reported_by
- [ ] usm_validate accepts a feedback file
init-persists-policy
usm init writes a valid feedback block and never leaves policy ambiguous
Acceptance criteria:
- [ ] Both prompts answered or defaulted (human-gate) if skipped
- [ ] Resulting system.usm passes schema validation
smart-merge-preserved
Generator additions respect existing smart-merge guarantees
Acceptance criteria:
- [ ] Feedback block rendered between USM markers only
- [ ] Hand-written content outside markers unchanged
Tests
setup-with-gh-auth
Given:
- interactive_init: true
- gh_authenticated: true
Then:
- assertion: Prompt offers all three policies
- assertion: Direct-to-github selectable
- assertion: Resulting system.usm feedback block validates
setup-without-gh-auth
Given:
- interactive_init: true
- gh_authenticated: false
Then:
- assertion: Direct-to-github NOT offered or warned against
- assertion: Default selection is human-gate
- assertion: feedback.github_auth persisted as false
human-gate-default
Given:
- system_usm_with_feedback_policy: "human-gate"
Then:
- assertion: Rules files instruct agent to ask human before filing
- assertion: No instruction to autonomously write feedback files
direct-to-github-renders-tracker
Given:
- system_usm_feedback_policy: "direct-to-github"
- identity_repository: "https://github.com/org/repo"
Then:
- assertion: Rules files reference https://github.com/org/repo/issues
- assertion: Mentions gh issue create and bug_report template
mcp-tool-validates
Given:
- malformed_feedback_payload: true
Then:
- assertion: usm_report_feedback rejects invalid kind/severity
- assertion: No file written on validation failure
mcp-tool-writes-entry
Given:
- valid_feedback_payload:
Then:
- assertion: File written to .usm/feedback/<slug>.usm
- assertion: $type: feedback and schema-valid
Implementation
- Primary: src/mcp/feedback.ts; src/scan/feedback.ts; src/generators/rulesFiles.ts
- Test code: tests/generate.test.ts
- Test code status: manual
See Also
- usm/gen-rules-files
- usm/gen-agentsmd
- usm/mcp-write
- usm/schema-v1
- usm/cli-init