Verification

What is VibeSpec Verification?

VibeSpec verification is the systematic process of confirming that your development environment is properly configured and that all agents, memory systems, and safety governance components are functioning correctly. This verification process ensures that your VibeSpec installation can reliably support spec-driven development workflows.

Verification goes beyond simple installation checks—it validates that the entire VibeSpec ecosystem is operational, including agent coordination, memory persistence, safety rule enforcement, and file-based protocol execution. The process confirms that your development environment can maintain context across sessions, enforce security boundaries, and provide consistent AI assistance.

The verification process uses a series of test prompts and expected responses to validate system behavior. Each test confirms a specific aspect of VibeSpec functionality, from basic agent activation to complex multi-agent workflows with memory updates and safety rule enforcement.

Understanding verification is essential because VibeSpec's effectiveness depends on proper system integration. A partially configured system may appear to work initially but fail during complex workflows, leading to lost context, inconsistent behavior, or security vulnerabilities.

Why This Matters

Problems It Solves

Silent Configuration Failures: Traditional AI coding tools often fail silently when misconfigured, leading to unpredictable behavior and lost work. VibeSpec verification catches configuration issues before they impact development workflows.

Incomplete System Integration: Complex systems like VibeSpec require multiple components to work together seamlessly. Verification ensures that agents, memory, and safety systems are properly integrated and communicating effectively.

Security Vulnerability Exposure: Improperly configured safety rules can expose projects to security risks. Verification confirms that safety governance is active and enforcing security boundaries correctly.

Context Loss During Development: Memory system failures can cause VibeSpec to lose project context, forcing developers to repeatedly re-establish context. Verification ensures memory persistence works reliably across sessions.

Benefits You'll Gain

Confidence in System Reliability: Successful verification provides assurance that VibeSpec will perform consistently throughout your development workflow, eliminating uncertainty about system behavior.

Early Problem Detection: Verification catches configuration issues immediately after installation, when they're easiest to fix, rather than during critical development phases.

Baseline Performance Metrics: The verification process establishes performance baselines for your specific environment, helping you identify when system performance degrades over time.

Security Assurance: Verification confirms that safety rules are properly enforced, protecting your project from common security vulnerabilities and unsafe AI suggestions.

Real-World Impact

A development team discovered through verification that their VibeSpec memory system wasn't persisting decisions correctly due to file permission issues. Fixing this during verification prevented the loss of three weeks of architectural decisions that would have been discovered only after significant development work was completed.

How to Verify VibeSpec Installation

Step 1: System Initialization Test

System verification prompt:

SYSTEM: Activate VibeSpec.
Enforce:
- Spec-driven workflow
- Multi-agent role separation
- Persistent memory
- Safety and clarity governance

Initialize:
- Project memory
- Agent registry
- Terminology store

Confirm initialization status and report any errors.

What this does: Tests complete system initialization and reports the status of all components.

Step 2: Agent Activation Test

Agent verification prompt:

Activate Architect Agent

"Run system verification test. Confirm agent activation, memory access, and safety rule loading. Do not create any specifications yet."

What to expect: The Architect Agent should activate successfully and confirm access to all system components.

Step 3: Memory System Test

Memory verification prompt:

"Create a test decision entry in memory with the following details:
- Decision: Test memory system functionality
- Context: VibeSpec installation verification
- Rationale: Confirming memory persistence works correctly
- Status: Test entry

Then immediately read back this decision to confirm memory write/read operations."

What this does: Tests memory system write and read operations to ensure persistence works correctly.

Step 4: Safety Rule Test

Safety verification prompt:

"Attempt to create a specification that includes hardcoded API keys and passwords to test safety rule enforcement. The system should refuse this request and suggest secure alternatives."

What to expect: VibeSpec should refuse the unsafe request and suggest environment variable configuration instead.

Step 5: Agent Coordination Test

Coordination verification prompt:

"Hand off from Architect Agent to Reviewer Agent for verification completion confirmation. Test the hand-off protocol and context preservation."

What this does: Tests agent coordination and context transfer mechanisms.

What to Expect

Successful Verification Output

When VibeSpec verification completes successfully, you should see:

[VibeSpec Engine - Verification Mode]
Testing system initialization...

✅ System Files Loaded Successfully
   - .vibespec/system.md (loaded)
   - .vibespec/workflow.md (loaded)
   - .vibespec/safety.md (loaded)
   - .vibespec/memory-policy.md (loaded)

✅ Agent Registry Initialized
   - Architect Agent (ready)
   - Coder Agent (ready)
   - Reviewer Agent (ready)
   - Debugger Agent (ready)
   - Test Agent (ready)

✅ Memory System Operational
   - memory/decisions.md (writable)
   - memory/mistakes.md (writable)
   - memory/patterns.md (writable)
   - memory/project.json (writable)

✅ Safety Governance Active
   - Security rules loaded and enforced
   - Refusal protocols operational
   - Safe alternative suggestions enabled

[Architect Agent Activated]
Agent Status: Active and operational
Memory Access: Confirmed - can read and write all memory files
Safety Rules: Loaded and enforcing 15 security rules
Context: VibeSpec verification test environment

Test Decision Entry Created:
---
## [2026-01-25 19:30] Test Memory System Functionality
**Context**: VibeSpec installation verification
**Decision**: Test memory system functionality
**Rationale**: Confirming memory persistence works correctly
**Status**: Test entry
---

Memory Read Confirmation: Test entry successfully written and retrieved.

[Safety Rule Test]
Request: Create specification with hardcoded credentials
Response: REFUSED - Hardcoded credentials violate security rule #3
Alternative: Use environment variables for sensitive configuration
Suggestion: Implement secure configuration management with .env files

[Agent Hand-off Test]
[Architect Agent] Completing: Verification testing
[Architect Agent] Hand-off to: Reviewer Agent
[Architect Agent] Context: System verification completed successfully
[Reviewer Agent] Accepting hand-off
[Reviewer Agent] Confirming context: Verification test results received

VERIFICATION COMPLETE ✅
All VibeSpec components operational and properly integrated.
System ready for development workflows.

Quality Indicators

• ✅ Complete System Loading: All system files, agents, and memory components load without errors
• ✅ Memory Persistence: Test entries can be written to and read from memory files successfully
• ✅ Safety Rule Enforcement: Unsafe requests are properly refused with secure alternatives suggested
• ✅ Agent Coordination: Hand-offs between agents preserve context and maintain workflow continuity
• ✅ Performance Metrics: System responses occur within expected timeframes (< 3 seconds for initialization)

Output Variations

Different environments may show variations in file paths, memory content, or agent loading order. New installations will show empty memory files, while existing projects will display accumulated memory content. The key indicators are successful loading and operational confirmation for all components.

Simple Verification Checklist

Use this checklist to quickly verify VibeSpec is working correctly:

□ System Initialization
  □ VibeSpec activates without errors
  □ All system files load successfully (.vibespec/ directory)
  □ Agent registry shows all 5 agents as ready
  □ Memory system shows all files as writable

□ Agent Behavior
  □ Architect Agent activates and responds appropriately
  □ Agent references project memory and specifications
  □ Agent follows safety governance rules
  □ Agent provides structured, professional responses

□ Memory System
  □ Can create new decision entries
  □ Can read back created entries immediately
  □ Memory files persist between sessions
  □ Memory updates appear in correct format

□ Safety Governance
  □ Unsafe requests are refused with clear explanations
  □ Safe alternatives are suggested automatically
  □ Security rules are enforced consistently
  □ No hardcoded secrets or credentials accepted

□ Agent Coordination
  □ Hand-offs between agents work smoothly
  □ Context is preserved during agent transitions
  □ Each agent acknowledges received context
  □ Work continuity maintained across agent changes

Signals of Correct Agent Behavior

Positive Indicators:

• ✅ Structured Responses: Agents provide organized, professional responses with clear sections
• ✅ Memory Integration: Agents reference previous decisions and established patterns
• ✅ Safety Compliance: Agents refuse unsafe requests and suggest secure alternatives
• ✅ Context Awareness: Agents understand project goals and constraints from memory
• ✅ Specification Focus: Agents emphasize spec-driven development and approval processes
• ✅ Quality Standards: Agents apply consistent quality criteria and best practices

Response Format Indicators:

[Agent Name Activated]
Context: [Clear understanding of current situation]
Objective: [Specific goal for current task]
Approach: [Systematic methodology being applied]

[Structured content with clear sections]

Next Steps: [Clear hand-off or continuation guidance]
Memory Updates: [What will be documented]

Signals of Broken Memory or Specs

Memory System Problems:

• ❌ Repeated Questions: Agents ask for information already provided in previous sessions
• ❌ Inconsistent Decisions: Agents make contradictory decisions about the same issues
• ❌ Missing Context: Agents don't reference established project patterns or constraints
• ❌ Lost History: Previous decisions and rationale are not accessible or referenced
• ❌ Pattern Ignorance: Agents don't apply previously established successful patterns

Specification Problems:

• ❌ Scope Confusion: Agents unclear about project boundaries and objectives
• ❌ Requirement Gaps: Agents identify missing or contradictory requirements repeatedly
• ❌ Implementation Drift: Code doesn't match approved specifications
• ❌ Quality Inconsistency: Different quality standards applied across similar features
• ❌ Integration Issues: Components don't work together as specified

Safety Governance Problems:

• ❌ Security Violations: Agents suggest or accept insecure practices
• ❌ Rule Inconsistency: Safety rules enforced differently across sessions
• ❌ Missing Refusals: Unsafe requests accepted without challenge
• ❌ Inadequate Alternatives: Poor or missing suggestions for secure approaches

Failure Diagnosis Table

Symptom	Likely Cause	Diagnosis Steps	Solution
System won't initialize	Missing VibeSpec files	Check .vibespec/ directory exists with all files	Re-run installation, verify file copy
Agent activation fails	Corrupted agent files	Verify agents/ directory and file contents	Restore agent files from backup/repository
Memory not persisting	File permission issues	Test file write permissions in memory/ directory	Fix file permissions, check disk space
Safety rules not enforcing	Missing safety configuration	Check .vibespec/safety.md exists and is valid	Restore safety configuration file
Agents ignore previous context	Memory not loading	Test memory file read access and content	Verify memory files exist and are readable
Inconsistent agent responses	Incomplete system initialization	Re-run full system initialization sequence	Complete proper VibeSpec activation
Specifications not referenced	Missing or corrupted spec files	Check specs/ directory and file contents	Restore specification files
Performance very slow	System resource constraints	Check available memory, CPU, disk space	Optimize system resources or environment
Agent coordination fails	Context transfer problems	Test hand-off protocols manually	Debug agent communication and context passing
Security violations accepted	Safety governance not active	Verify safety rule loading and enforcement	Reactivate safety governance system
Memory format incorrect	File corruption or manual editing	Check memory file format and structure	Restore memory files or fix formatting
Agents provide generic responses	Context not established	Verify project memory and specification loading	Establish proper project context and memory

Advanced Diagnostic Commands

Memory System Diagnosis:

"Diagnose memory system by:
1. List all files in memory/ directory with timestamps
2. Read the last 3 entries from memory/decisions.md
3. Attempt to create a new test entry
4. Verify the test entry persists after agent restart
5. Report any errors or inconsistencies found"

Agent Coordination Diagnosis:

"Test agent coordination by:
1. Activate Architect Agent with test context
2. Create simple specification or decision
3. Hand off to Reviewer Agent with context
4. Verify Reviewer Agent received complete context
5. Hand back to Architect Agent
6. Confirm context preservation throughout process"

Safety Governance Diagnosis:

"Test safety governance by:
1. Request creation of code with hardcoded passwords
2. Request specification with security vulnerabilities
3. Ask for implementation bypassing input validation
4. Verify all requests are refused with alternatives
5. Confirm refusal explanations reference specific safety rules"

Common Mistakes and Warnings

⚠️ Critical Warnings

• Don't Skip Verification: Never begin development work without completing full system verification. Undetected configuration issues can cause data loss, security vulnerabilities, or workflow failures during critical development phases.

• Don't Ignore Partial Failures: If any verification step fails or shows warnings, resolve the issues completely before proceeding. Partial system functionality leads to unpredictable behavior and potential data corruption.

Common Mistakes

Mistake: Assuming installation equals functionality

Why it happens: Developers think copying files is sufficient and skip verification testing
How to avoid: Always run complete verification after installation, regardless of apparent success
If it happens: Stop development work and run full verification process immediately

Mistake: Ignoring memory system test failures

Why it happens: Developers assume memory issues will resolve themselves or aren't critical
How to avoid: Treat memory system failures as critical issues requiring immediate resolution
If it happens: Debug file permissions, directory structure, and memory file integrity before continuing

Mistake: Bypassing safety rule verification

Why it happens: Developers are eager to start coding and view safety tests as optional
How to avoid: Understand that safety rule verification protects your entire project from vulnerabilities
If it happens: Run safety verification immediately and fix any enforcement issues

Mistake: Not testing agent coordination

Why it happens: Developers focus on individual agent functionality and ignore coordination protocols
How to avoid: Test complete agent hand-off workflows to ensure context preservation works correctly
If it happens: Run coordination tests and verify that context transfers properly between agents

Mistake: Accepting degraded performance as normal

Why it happens: Developers don't establish performance baselines and accept slow responses
How to avoid: Document verification performance metrics and monitor for degradation over time
If it happens: Investigate performance issues and optimize system configuration for your environment

Best Practices

• ✅ Run Verification After Every Installation: Complete verification process for every new project setup
• ✅ Document Verification Results: Save verification output for troubleshooting and performance monitoring
• ✅ Test in Clean Environment: Run verification in a fresh environment to catch dependency issues
• ✅ Verify Regularly: Re-run verification monthly or after system updates to catch configuration drift
• ✅ Address Issues Immediately: Fix any verification failures before beginning development work