vsdd-factory

Browser-based visual companion for showing mockups, diagrams, and interactive options during brainstorming, brief creation, and architecture design. Runs a local Node.js server that watches for HTML files and serves them with live reload. Optional — requires Node.js.

Write a verified HANDOFF.md (9 base required fields) and an atomically co-committed wave-state.yaml (6 required fields) to the factory-artifacts branch at wave close. Provides the lossless wave-boundary checkpoint required by BC-5.41.001 and BC-5.41.002.

Computes wave-based implementation order from story dependencies. Groups stories into waves for parallel execution within each wave.

Diagnostic check of STATE.md — validates structure, size, phase numbering, frontmatter, and content routing compliance. Reports HEALTHY, WARNINGS, or NEEDS-COMPACT.

Extract historical content from STATE.md into cycle files (burst logs, adversary passes, session checkpoints, lessons). Slims STATE.md to <200 lines.

Rehydrate session context at the start of a new session after a wave-boundary reset. Reads wave-state.yaml EXCLUSIVELY from the factory-artifacts branch via git show, injects exactly the listed spec files (Set(stories[*].spec_files) ∪ Set(arch_files) ∪ {state_pointer}), and pauses for operator confirmation before any pipeline work begins. Satisfies BC-6.24.001 postconditions 1–8 and VP-088 §1–§4.

Full wave-boundary reset procedure. Clears the current session, starts a new session, and runs /rehydrate-wave as the mandatory first step to restore exactly the next-wave spec context from wave-state.yaml on factory-artifacts. Pairs with /wave-handoff (which produces the manifest) to provide lossless context-window transitions (CAP-032).

Execute the Single-Commit Burst Protocol (TD-VSDD-053) for state-manager remediation bursts. One atomic commit per burst — no Stage 2 backfill, no SHA placeholder, no chain. Refuses in-progress narrative voice and reintroduction of the retired two-commit pattern.

Validate and auto-repair the .factory/ worktree. Run at session start or when .factory/ state seems wrong. Checks orphan branch exists, worktree is mounted, and STATE.md is present.

Acquire the cross-session factory lock on the factory-artifacts orphan branch. Performs fetch-before-check (BC-6.23.001 Precondition 2), then CAS-protected push via state-manager delegation. No direct STATE.md write — all writes go through state-manager (BC-6.23.001 Invariant 5 / AC-011).

Release the cross-session factory lock. Plain release (self-held only) or --force break-glass release (any lock, mandatory audit event). No direct STATE.md write — all writes go through state-manager (BC-6.23.001 Invariant 5 / AC-011).

Validates factory worktree health on pipeline start. Checks .factory/ (all modes) and .factory-project/ (multi-repo only). Verifies remote branch existence, local worktree mount, and sync state. Auto-repairs if possible. Runs on ALL pipeline modes (greenfield, brownfield, feature, resume). Executed by devops-engineer.

Launch a fresh-context adversarial review of specs or implementation. Uses the adversary agent with information asymmetry to find gaps, contradictions, and missing edge cases. Minimum 3 clean passes to convergence.

Use when delivering a single story through the VSDD TDD pipeline. Dispatches fresh specialist subagents (test-writer → implementer → demo-recorder → pr-manager → devops-engineer) via the per-story-delivery orchestrator workflow. Each step runs in isolated context to preserve reasoning quality and prevent context exhaustion.

Post-convergence code delivery workflow. Pushes verified code to remote, creates PRs with structured evidence, waits for CI, and executes merge based on autonomy level. Handles greenfield, brownfield, feature, and maintenance mode PRs.

Streamlined delivery flow for fix PRs created during adversarial refinement, formal hardening, and convergence. Same rigor as story PRs (worktree, AI review, security review) but skips stubs, Red Gate, and wave integration gates.

Monitors competitor activity: new releases, feature announcements, pricing changes, funding rounds, acquisitions. Produces a competitive update report that feeds into the synthesis layer.

Ingests customer feedback from configured channels (GitHub issues, support tickets, app reviews, Slack/Discord). Categorizes, deduplicates, and produces a structured feedback digest. Does not interact with customers.

Autonomous discovery engine that continuously researches opportunities for both new features (existing products) and new product concepts. Evaluates ideas against structured criteria, facilitates planning document creation, and routes approved ideas to the appropriate development pipeline.

Creates behavioral clones of third-party services for the Digital Twin Universe. Agents build clones from API documentation, OpenAPI specs, and recorded traffic. Clones are packaged as Docker containers for use in testing and holdout evaluation.

Interactive, facilitated workflow that guides the human from raw ideas to a structured product brief. Uses staged elicitation — understand intent first, then fill sections through conversation, then draft and review. Inspired by the BMAD Method's collaborative discovery pattern.

Correlates signals across market research, customer feedback, and usage analytics to produce scored insights. Clusters related signals into themes, calculates evidence strength, and feeds into DF-017's scoring framework.

Mandatory market intelligence assessment that runs before any spec work begins. Researches competitive landscape, validates customer pain, assesses market size, identifies differentiation opportunities, and flags risk signals. Produces a GO / CAUTION / STOP recommendation for human review.

Conducts market, domain, and technical research to validate assumptions and fill knowledge gaps before brief or PRD creation. Uses Perplexity deep research (perplexity_research) for web research, Context7 for library/framework documentation, and Tavily for cross-validation. Can run domain, market, or technical research independently or combined.

After a feature ships, monitors feedback channels and analytics for signals about the feature's reception. Runs at configured intervals (e.g., 7 days, 30 days, 90 days post-ship). Produces a feature impact report.

Interactive repository creation flow. Orchestrator gathers requirements from human, devops-engineer creates repo with standard configuration.

Operate the research-cache for Perplexity/Context7 query results (especially expensive perplexity_research deep-research calls). Check, inspect, and clear cached research to avoid re-running expensive queries.

Conduct external research — domain analysis or technology evaluation. Spawns the research-agent with MCP tool access (Perplexity deep research via perplexity_research, Context7, Tavily). Usage - /research domain <topic> or /research <topic> for general.

Config-driven release pipeline: version bump, CHANGELOG update, git tagging, GitHub Release, registry publishing. Reads .factory/release-config.yaml. Supports bootstrap (init), release, and dry-run modes.

Run the post-wave integration gate — full test suite on develop, adversarial review of wave diff, holdout evaluation, demo evidence validation, and DTU validation for critical modules. Blocks next wave until all checks pass.

Scan .factory/ for artifact files whose paths do not match the canonical patterns in artifact-path-registry.yaml. Default mode is dry-run (table of violations, no filesystem changes). Pass --apply to execute git mv and update cross-references.

Fix structural gaps in a VSDD artifact file by adding missing frontmatter fields, section headings, and table structures from its template. Preserves all existing content — never deletes, only adds structure.

Scaffold a new ADR file from template, allocate collision-free ID, insert ARCH-INDEX row, patch any superseded ADR bidirectionally, and validate template compliance. Atomic-or-nothing execution.

Create sharded architecture documents from PRD and behavioral contracts. Designs system architecture with ADR-style decisions, component diagrams, and purity boundaries. Writes to .factory/specs/architecture/.

Create a product brief through guided discovery. Asks questions to understand the product vision, users, constraints, and success criteria. Writes to .factory/specs/product-brief.md.

Create a sharded L2 domain specification from the product brief. Models the problem domain — entities, relationships, processes, invariants, and ubiquitous language. Writes to .factory/specs/domain-spec/.

Use when generating architecture diagrams, entity relationships, flow charts, or any visual diagram as an .excalidraw JSON file. Files can be viewed in excalidraw.com, VS Code, or the visual companion browser.

Create a PRD with behavioral contracts from the product brief and domain spec. Elaborates requirements into testable contracts with error taxonomy and edge cases. Writes to .factory/specs/prd.md and supplements.

Create or refine a single story spec with full acceptance criteria, tasks, and implementation details. Takes a story ID and produces a sprint-ready story file.

Product Owner revises PRD v1 based on Architect's feasibility review. Incorporates architectural feedback, updates subsystem grouping if justified. Max 3 iterations before escalation to human.