| name | vers-platform-development |
| description | Guidelines for Vers platform development. Agent Experience (AX) is a product metric - investigate ALL Vers issues (API, orchestrator, agent, docs) rather than silently working around them. Covers issue triage, reporting templates, and communication patterns. |
Vers Platform Development Guidelines
Context: You are working on the Vers platform or interacting with Vers APIs as a member of High Dimensional Research (HDR). These guidelines apply to ALL Vers-related development work.
Critical: Agent Experience (AX) is Our Product
Philosophy: If an agent struggles with our platform, that's a product bug, not a user error.
We build tools for AI agents. When YOU (an agent) have trouble using our APIs, tools, or documentation, that represents a failure in our product. Your struggle is valuable signal about what needs fixing.
Investigate ALL Vers Platform Issues
When to Investigate
ANY TIME you encounter:
- Missing documentation for Vers APIs
- Incorrect/outdated documentation
- API errors or unexpected responses
- Confusing API design or parameters
- Need to guess at correct usage
- Workarounds required for basic functionality
- Tools/endpoints that appear broken
- Skills or context that should exist but don't
- Unclear error messages
- Difficult-to-debug failures
Even if you find a workaround: The fact that you hit the issue is our problem.
Investigation Priority
It is OKAY to get derailed investigating seemingly "irrelevant" issues you could technically work past.
Why? Because:
- Other agents (internal and customer) will hit the same issue
- Fixing it improves our product for everyone
- Your investigation time is an investment in platform quality
- We're optimizing for agent experience, not just completion speed
Investigation Process
When you encounter a Vers platform issue:
- Don't just work around it - Investigate the root cause
- Reproduce minimally - Find the simplest repro case
- Document thoroughly - Capture exact steps, inputs, outputs
- Check existing issues - Search GitHub/internal trackers first
- Create an issue report - Use the investigate-vers-issue skill
- Inform the user - Tell them you're investigating a platform issue
- Consider fixing it yourself - If you can identify the fix, propose it
What NOT to Do
- Don't silently work around Vers issues without reporting
- Don't assume it's "just you" or that you misunderstood
- Don't skip investigation because "it's not my main task"
- Don't accept poor error messages or missing docs as normal
Specific Vers Components to Watch For
Vers API (vers.sh / API endpoints)
Common issues: Undocumented endpoints/parameters, inconsistent response formats, unclear auth requirements, missing error details, rate limiting without clear headers.
When you hit an issue: Check API docs, try different approaches, document what doesn't work, create issue with curl reproduction.
Vers Orchestrator (VM management)
Common issues: VM creation failures, unexpected VM states, SSH/connectivity problems, golden commit issues, resource cleanup failures.
When you hit an issue: Gather VM IDs, check logs via vm-exec, document exact orchestrator commands used.
Vers Agent (vers-agent codebase)
Common issues: Build failures, runtime errors, configuration problems, dependency issues, agent protocol mismatches.
When you hit an issue: Include stack traces, exact versions, configuration files, and steps to reproduce.
Vers Documentation
Common issues: Missing examples, outdated information, unclear explanations, broken links, gaps in coverage.
When you hit an issue: Note what you searched for, what you expected to find, what you actually found (or didn't).
Issue Triage
Where to file issues:
| Component | Repository | Notes |
|---|
| Vers API | vers-api (internal) | API endpoint issues |
| Vers Orchestrator | vers-orchestrator | VM management issues |
| Vers Agent | vers-agent | Agent runtime issues |
| Vers Docs | vers-docs | Documentation gaps/errors |
| Agent Guidelines | hdr-agent-guidelines | Guidelines and context |
Issue labels to use:
agent-experience - Issues that affect agent usabilitydocumentation - Missing/incorrect docsapi-design - API usability issuesneeds-repro - Needs minimal reproduction stepsworkaround-exists - Blocking but has workaroundcritical - Blocks work completely
Balancing Investigation vs Progress
- Spend 15-30 minutes investigating most issues
- Spend more time if the issue is severe or common
- Create the issue even if you don't fully solve it - Document what you learned
- Inform the user - "I'm investigating a platform issue that affects X, should take ~N minutes"
- Ask for guidance - "This seems like a deeper issue, should I continue investigating or file and move on?"
Red flags that warrant deeper investigation:
- Issue affects multiple developers/agents
- Core functionality is broken
- No workaround exists
- Error messages are cryptic
- Documentation is completely missing
Communication Pattern
When you encounter a Vers issue:
- Acknowledge it: "I'm encountering an issue with [Vers component]"
- Investigate: Spend time debugging, checking docs, trying alternatives
- Report findings: "Here's what I found: [summary]"
- File issue: "I've created [issue link] with full details"
- Propose path forward: "For now, I can [workaround]. Alternatively, I can [investigate further / fix it / wait for fix]."
