How to Build Consistent AI Coding Workflows with Viserys

What Is Viserys?

Viserys is a self-contained collection of engineering workflows for AI coding agents. Instead of allowing an agent to invent a process for every request, it supplies reusable Markdown instructions, reviewer personas, shared references, lifecycle commands, evaluation fixtures, and validation scripts.

The project organizes software work into a six-stage lifecycle:

DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP

Each workflow lives in a SKILL.md file and includes procedural steps, exit criteria, and anti-rationalization guidance. Because the skills are plain Markdown, they can be loaded by skill-aware coding agents or read directly as standalone instructions.

Key Features

• Lifecycle coverage: Workflows cover requirements, planning, implementation, testing, review, and release preparation.
• 26 packaged skills: The skills/ directory contains reusable engineering workflows.
• Reviewer personas: Specialized agents evaluate code quality, testing, security, and web performance.
• OpenCode integration: A primary-mode Viserys agent is included and loads the skills without global configuration.
• Shared references: Checklists can be loaded when needed rather than placed permanently in the agent context.
• Validation and evaluation: Node.js scripts check skills, commands, artifact paths, reference links, versions, and evaluation cases.

Understand the Repository Structure

• skills/ contains the skill workflows.
• agents/ contains four specialist reviewer personas.
• references/ provides shared, on-demand checklists.
• commands/ defines lifecycle commands.
• evals/ contains skill evaluation cases and fixtures.
• scripts/ contains validators and the evaluation runner.
• hooks/ provides session lifecycle hooks.
• docs/ contains internal documentation.
• .opencode/agent/viserys.md defines the OpenCode agent.
• .opencode/opencode.json registers the skill paths for OpenCode.

Installation and Setup

Option 1: Activate Viserys in OpenCode

1. Clone the Viserys repository with Git.
2. Open the cloned repository folder in OpenCode.
3. Press Tab to open the agent selector.
4. Select viserys.

The included Viserys agent runs in primary mode, so it appears in OpenCode's agent list. Its prompt checks for an applicable skill before processing a request and routes work through the project lifecycle. The repository-level OpenCode configuration registers all packaged skills, so no global configuration is required.

Option 2: Use Viserys with Another Skill-Aware Agent

For Claude Code, Cursor, or another agent that supports reusable skills, point the agent at the repository's skills/ directory. Alternatively, copy that directory into the tool's native skills location.

The exact destination depends on the coding agent. Viserys does not require its Markdown workflows to be converted into another format, but the host tool must know where to discover them.

Option 3: Use the Skills as Plain Context

If an agent has no native skill system, open the relevant SKILL.md file and provide its contents as context. Every skill is designed to stand alone, so you can follow its steps manually or instruct an agent to follow them.

Choose the Right Workflow

Start with the meta skill using-agent-skills when you are unsure which workflow applies. Otherwise, select a skill according to the current lifecycle stage.

DEFINE: Clarify the Work

• Use idea-refine when a concept is vague and needs structured exploration.
• Use interview-me when requirements must be collected one question at a time.
• Use spec-driven-development before starting a project, feature, or significant change without a specification.
• Use constraint-driven-development when no quality bar exists or checks are being suppressed merely to make the build pass.

PLAN: Turn a Specification into Tasks

After requirements are stable, use planning-and-task-breakdown. It converts a specification into ordered, verifiable tasks with acceptance criteria.

BUILD: Implement Deliberately

• incremental-implementation helps changes spanning multiple files land in thin slices.
• test-driven-development applies when implementing logic, correcting a bug, or changing behavior.
• context-engineering helps initialize a session, switch tasks, or recover when output quality declines.
• source-driven-development is appropriate when correctness depends on current official documentation.
• doubt-driven-development encourages verification when the stakes are high and checking now is cheaper than debugging later.
• frontend-ui-engineering guides user-facing interface work.
• api-and-interface-design supports API, module boundary, and public interface design.

VERIFY: Prove the Change Works

• Use browser-testing-with-devtools for browser-based implementation or debugging.
• Use debugging-and-error-recovery when a test fails, a build breaks, or runtime behavior is unexpected.

REVIEW: Evaluate Quality and Risk

• code-review-and-quality should be used before merging a change.
• code-simplification is useful when working code remains difficult to understand or maintain.
• security-and-hardening applies to user input, authentication, data storage, and external integrations.
• performance-optimization applies when performance requirements exist or a regression is suspected.

SHIP: Prepare for Production

• git-workflow-and-versioning guides code changes and version control.
• ci-cd-and-automation supports build and deployment pipeline changes.
• deprecation-and-migration helps remove old systems or migrate users.
• documentation-and-adrs records architectural decisions and public API changes.
• observability-and-instrumentation covers logs, metrics, traces, and alerts.
• shipping-and-launch guides final production deployment preparation.

Basic Usage Example

Suppose you ask an AI coding agent to add a new authenticated API endpoint. Rather than jumping directly into implementation, apply the lifecycle in sequence.

1. Define: Run interview-me if authentication rules, inputs, or responses are unclear. Then use spec-driven-development to establish the expected behavior.
2. Plan: Apply planning-and-task-breakdown to produce ordered tasks and acceptance criteria.
3. Build: Use api-and-interface-design for the endpoint contract and test-driven-development for the behavior. If several files must change, also use incremental-implementation.
4. Verify: If tests fail or the endpoint behaves unexpectedly, follow debugging-and-error-recovery.
5. Review: Apply code-review-and-quality and security-and-hardening because the feature handles authentication and input.
6. Ship: Use the appropriate Git, documentation, observability, and launch workflows before production deployment.

With the OpenCode integration enabled, the Viserys agent is designed to check for matching skills first. In a plain-context setup, you perform this selection yourself and ask the agent to follow each chosen Markdown workflow.

Use the Reviewer Personas

Viserys includes four reviewer personas in agents/. They provide focused perspectives that complement the lifecycle skills.

• agents/code-reviewer.md performs a five-axis review using a staff-engineer approval standard.
• agents/test-engineer.md examines test strategy and coverage using the prove-it pattern.
• agents/security-auditor.md covers vulnerability detection, threat modeling, and OWASP assessment.
• agents/web-performance-auditor.md audits Core Web Vitals in quick or deep modes.

Choose a persona based on the risks of the change. For example, pair the security auditor with security-and-hardening for authentication work, or use the web performance auditor after modifying a user-facing interface.

Validate the Workflow Pack

Run the supplied Node.js scripts after changing skills, commands, references, versions, or evaluation fixtures:

node scripts/validate-skills.js
node scripts/validate-commands.js
node scripts/validate-artifact-paths.js
node scripts/validate-reference-links.js
node scripts/validate-versions.js
node scripts/run-evals.js

These commands validate the pack's internal structure and run its evaluation suite. They are especially important when extending Viserys rather than merely consuming its existing workflows.

Advanced Tips

Combine Skills Without Skipping Lifecycle Gates

A task may require more than one skill. A browser feature, for example, can combine frontend-ui-engineering, test-driven-development, and browser-testing-with-devtools. Keep each skill's exit criteria visible so that adding workflows does not turn into unstructured prompting.

Load References Only When Needed

The references/ directory is intended for shared checklists loaded on demand. This helps keep an agent's active context focused while preserving access to detailed guidance.

Use Official Sources for Version-Sensitive Work

Apply source-driven-development when implementation details depend on current documentation. Pair it with doubt-driven-development when a plausible but incorrect assumption would be costly.

Recover When Agent Quality Declines

If a long session becomes inconsistent, use context-engineering. It is specifically intended for session setup, task switching, and situations where output quality has dropped.

Consult the Included Documentation

• docs/README.md explains the pack and lifecycle map.
• docs/skill-anatomy.md defines the SKILL.md format.
• evals/README.md explains how skill evaluation works.

Read the skill anatomy specification before adding or restructuring workflows, then run the validators and evaluations to check the result.

Conclusion

Viserys turns AI-assisted development into a repeatable engineering process. Start by connecting the skills/ directory to a compatible agent or selecting the bundled Viserys agent in OpenCode. Then move deliberately through DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP, using specialist personas and validation scripts where they add value.