Orchestrata Ultimate / Specs / 030-architect-volk

030-architect-volk: Architect Volk (U:Ar)

U:Ar is the Architect volk — the design authority in the Orchestrata pipeline. It receives validated requirements from U:PM (or UX artifacts from U:Ux) and produces five structured architecture artifacts: an architecture document, a file tree, an API spec, a class diagram, and a requirements document. It uses call_reasoner() — a reasoning-tier LLM (deepseek-reasoner or Claude Opus) — to perform deep architectural thinking via structured chain-of-thought decomposition. Designs are reviewed...

At a glance

Reading this spec

U:Ar, the Architect Volk, is the design authority in the Orchestrata pipeline. It receives validated requirements from U:PM (or UX artifacts from U:Ux) and produces five structured artifacts: an architecture document, a file tree, an API spec, a class diagram and a requirements document. It does this with call_reasoner(), a reasoning-tier LLM call (deepseek-reasoner or Claude Opus) that uses structured chain-of-thought decomposition. Without it, generated projects have no coherent architecture, juniors lack unambiguous contracts and the architect would re-invent types that already exist.

The scope is eight user stories: initial architecture generation, the design feedback loop, monorepo context injection, project scaffold creation and design escalation to the CodeDirector (critical), and UX design integration, structured requirements propagation and graceful degradation (high). Requirement IDs use the REQ-030- prefix.

The flow stated in the overview is as follows. U:PM sends scope_validated (or U:Ux sends ux_complete). U:Ar queries Neo4j for existing monorepo types and the project tree, calls the reasoner with its prompt template and the injected context, and parses the response into five sections: ARCHITECTURE, REQUIREMENTS, FILE_TREE, API_SPEC and CLASS_DIAGRAM. The design docs are written to the project's design/ directory and committed to git. U:Ar sends a design_review packet to J:Junior and iterates on the junior's feedback, using an update template, until the verdict is READY or the design cycles reach MAX_DESIGN_CYCLES. It then escalates to U:Cd with an implement packet carrying all five artifacts and the monorepo context.

In the code, the largest tracers are orchestrata_ultimate/agents/volks/architect/volk, orchestrata_ultimate/agents/volks/architect/architect_project and orchestrata_ultimate/agents/volks/architect/architect_context. The per-requirement view is on the RTM page.

The spec's status line reads Implemented. It tracks 6 files and defines 45 requirement IDs. The full text follows below.

Measured coverage is 43 of 45 requirements cited by at least one @traces in src/ (95.6%), spread over 3 modules; the module citing the most of them is orchestrata_ultimate/agents/volks/architect/volk (25 requirements). In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: 2 requirements have no citing symbol. The largest untraced groups are REQ-030-* (2). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (0 against 43).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

Checklists

checklists/constitutional.md

Architect Volk (U:Ar) — Constitutional Compliance Checklist

Component: ArchitectVolk, ArchitectContextMixin, ArchitectProjectMixin Spec: 030-architect-volk Status: Compliance Review Total Compliance Items: 15

Overview

This document tracks compliance of the Architect Volk (U:Ar) with the Orchestrata Constitution. U:Ar is the design authority in the pipeline. Its constitutional obligations focus on: owning only its design artifacts (Article I), deferring governance to Prolog (Article II), maintaining session isolation per design thread (Article III), logging all design transitions (Article IV), not fabricating completed designs (Article V), producing complete artifacts before escalation (Article VI), using real LLM calls in tests (Article VII), exposing metrics on design cycle counts (Article VIII), degrading gracefully when Neo4j or tools are absent (Article IX), supporting version evolution (Article X), and maintaining this spec as the documentation authority (Article XI).

Article I: Agent Autonomy and Ownership Boundaries

Principle: U:Ar owns design artifacts within the project_dir it created. It does not modify files owned by other agents or outside its project workspace.

Compliance Requirements

• [x] CONST-030-001: U:Ar writes design artifacts exclusively to {project_dir}/design/ and never to other agents' workspaces
• [x] CONST-030-002: process() returns None for unrecognized subjects — does not attempt to handle another agent's packets
• [x] CONST-030-003: U:Ar does not modify incoming CXP packets; it produces new packets only
• [x] CONST-030-004: escalation_target set at construction time ("U:Cd"); not overridden at runtime
• [x] CONST-030-005: _git_commit() operates only within the project_dir it initialized, never in the Orchestrata monorepo

Priority: Critical Verification: Code review of volk.py and architect_project.py; assert no writes outside project_dir

Article II: Prolog as Single Source of Truth

Principle: U:Ar does not duplicate or override governance logic. Policy decisions (who may see the design, when to escalate, what constitutes a valid design) are not hardcoded.

Compliance Requirements

• [x] CONST-030-006: Design iteration cycle limit (MAX_DESIGN_CYCLES) is a configurable constant, not a Prolog-backed policy — it enforces an operational ceiling, not a governance decision
• [x] CONST-030-007: U:Ar does not evaluate Prolog predicates directly; governance enforcement is delegated to the PAM++ layer

Priority: High Verification: grep for pyswip imports in architect package; assert none found

Article III: Session Isolation

Principle: Each design thread is isolated. U:Ar's state (design_docs, design_cycles, project_dir) belongs to a single thread_id and does not leak across concurrent requests.

Compliance Requirements

• [x] CONST-030-008: design_docs, design_cycles, project_name, and project_dir initialised in __init__() — each ArchitectVolk instance is thread-scoped
• [x] CONST-030-009: current_thread set from packet.thread_id at the start of each design request, ensuring context stays scoped

Priority: Critical Verification: Unit test with two concurrent packets to separate instances; assert no state cross-contamination

Article IV: Transparency and Logging

Principle: All design transitions (start, iteration, escalation) are logged. No silent drops.

Compliance Requirements

• [x] CONST-030-010: Every design phase transition is printed with agent tag [U:Ar] (start, iteration count, escalation, git commit)
• [x] CONST-030-011: Forced escalation at MAX_DESIGN_CYCLES prints a warning before proceeding

Priority: Critical Verification: Capture print output in tests; assert expected phase labels present

Article V: Non-Deception

Principle: U:Ar does not claim a design is complete until all five artifacts are written to disk and committed.

Compliance Requirements

• [x] CONST-030-012: _finalize_design() calls _write_design_docs() and _git_commit() before constructing the escalation CXP — artifacts are persisted before the claim of completion is made

Priority: Critical Verification: Integration test: assert design files exist on disk before implement CXP is returned

Article VI: Quality Gates

Principle: Designs must be complete (all five sections present) before escalation. Partial designs are not escalated silently.

Compliance Requirements

• [x] CONST-030-013: _finalize_design() includes all five design_docs values in the implement CXP payload, including empty strings — the downstream agent sees exactly what was produced, not a filtered subset

Priority: High Verification: Assert all five keys present in finalization packet payload

Article VII: Testing Without Mocks

Principle: Tests for U:Ar use real implementations — real file I/O, real subprocess calls for git and uv, real string parsing. No mock LLM responses (use synthetic string inputs directly).

Compliance Requirements

• [x] CONST-030-014: No unittest.mock, MagicMock, patch, or AsyncMock in any test file for orchestrata-architect
• [x] CONST-030-015: _parse_design(), _write_design_docs(), _init_project(), _git_commit(), and _slugify() tested with real file system operations in temporary directories

Priority: High Verification: grep -r "unittest.mock\|MagicMock" packages/orchestrata-architect/ returns empty

Summary

Last Updated: 2026-04-04 Version: 1.0.0 Maintained By: Mohamed

checklists/requirements.md

The requirement list above comes from this file; 45 of 45 checkbox items are ticked.

checklists/testing.md

Architect Volk (U:Ar) — Testing Plan

Component: ArchitectVolk, ArchitectContextMixin, ArchitectProjectMixin Spec: 030-architect-volk Status: Test Planning Phase Total Test Cases: 45

Overview

This document defines the comprehensive testing strategy for the Architect Volk (U:Ar). All tests follow the strict "no mocking" policy: real file I/O, real subprocess calls, real string parsing, and real Python object instantiation. Synthetic LLM responses are constructed as literal strings — the LLM itself is not invoked in unit tests (it is an external I/O boundary; its output is faked as a string fixture, not mocked via patch).

Test Categories Summary

Test Infrastructure

Test File Structure

tests/
├── test_architect_volk.py         # Unit: process(), _handle_design(), _handle_feedback()
├── test_architect_design.py       # Unit: _parse_design(), _write_design_docs(), _make_review_packet()
├── test_architect_fields.py       # Unit: _load_structured_fields(), _resolve_project_name(), _slugify()
├── test_architect_context.py      # Unit: ArchitectContextMixin methods
├── test_architect_project.py      # Integration: _init_project(), _write_context_json(), _git_*
└── test_architect_compliance.py   # Compliance: no mocks, ownership, transparency

Synthetic LLM Response Fixture

Tests that exercise parsing use a synthetic response string — not a mock:

SYNTHETIC_RESPONSE = (
    "ARCHITECTURE:\nComponent A handles X.\nComponent B handles Y.\n\n"
    "REQUIREMENTS:\nFUNCTIONAL:\n1. FR-01: The system must do X.\n\n"
    "FILE_TREE:\nsrc/\n├── app/\n│   └── main.py\ntests/\n└── test_main.py\n\n"
    "API_SPEC:\nModule: src/app/main.py\nFunctions:\n  run() -> None\n\n"
    "CLASS_DIAGRAM:\nclassDiagram\n  App --> Runner\n"
)

Unit Tests (28)

Process Routing (4 tests)

• [ ] TEST-030-UNIT-001: process() routes scope_validated to _handle_design() — verify return is design_review CXP addressed to J:Junior
• [ ] TEST-030-UNIT-002: process() routes ux_complete to _handle_design() — verify identical behavior to scope_validated
• [ ] TEST-030-UNIT-003: process() routes implement subject to _handle_design()
• [ ] TEST-030-UNIT-004: process() returns None for unknown subject "unknown_subject"

Parse Design (5 tests)

• [ ] TEST-030-UNIT-005: _parse_design() with well-formed 5-section response populates all five design_docs keys
• [ ] TEST-030-UNIT-006: _parse_design() with response missing FILE_TREE: marker leaves file_tree as empty string
• [ ] TEST-030-UNIT-007: _parse_design() with response missing all markers leaves all keys as empty string
• [ ] TEST-030-UNIT-008: _parse_design() correctly terminates each section at the next marker (no section bleeds into next)
• [ ] TEST-030-UNIT-009: _parse_design() strips leading/trailing whitespace from each section value

Feedback Handling (5 tests)

• [ ] TEST-030-UNIT-010: _handle_feedback() with verdict="READY" returns implement CXP addressed to U:Cd
• [ ] TEST-030-UNIT-011: _handle_feedback() with verdict="QUESTIONS" and cycle=1 < MAX_DESIGN_CYCLES returns design_review CXP
• [ ] TEST-030-UNIT-012: _handle_feedback() with cycle >= MAX_DESIGN_CYCLES returns implement CXP regardless of verdict
• [ ] TEST-030-UNIT-013: _finalize_design() payload contains all five design artifact keys
• [ ] TEST-030-UNIT-014: _finalize_design() payload contains project_dir, task_summary, original_intent, structured_requirements, user_stories, monorepo_src_section, nfrs, spec_metadata

Iterate Design (3 tests)

• [ ] TEST-030-UNIT-015: _iterate_design() increments design_cycles by 1
• [ ] TEST-030-UNIT-016: _iterate_design() formats questions as numbered list in prompt (verify question text in update prompt)
• [ ] TEST-030-UNIT-017: _iterate_design() returns design_review CXP addressed to J:Junior

Review Packet (2 tests)

• [ ] TEST-030-UNIT-018: _make_review_packet() returns CXP with subject="design_review" and to_agent="J:Junior"
• [ ] TEST-030-UNIT-019: _make_review_packet() includes design_cycle, project_dir, task_summary in payload

Structured Fields (4 tests)

• [ ] TEST-030-UNIT-020: _load_structured_fields() extracts all five structured fields from full payload
• [ ] TEST-030-UNIT-021: _load_structured_fields() prints impact_report when _impact_report present in parameters
• [ ] TEST-030-UNIT-022: _resolve_project_name() uses concierge project_name field when present (slugified)
• [ ] TEST-030-UNIT-023: _resolve_project_name() falls back to slugified task_summary when project_name absent

Slugify (5 tests)

• [ ] TEST-030-UNIT-024: _slugify("Hello World!") returns "hello-world"
• [ ] TEST-030-UNIT-025: _slugify("") returns "project" (default fallback)
• [ ] TEST-030-UNIT-026: _slugify("A" * 60) returns slug of at most 50 characters
• [ ] TEST-030-UNIT-027: _slugify("foo___bar") collapses underscores to single hyphen
• [ ] TEST-030-UNIT-028: _slugify("--leading--trailing--") strips leading and trailing hyphens

Integration Tests (12)

Project Scaffold (6 tests)

• [ ] TEST-030-INTEG-001: _init_project() in a real temp directory creates all 7 expected subdirectories (design, src, tests, tests/unit, tests/integration, docs, requirements)
• [ ] TEST-030-INTEG-002: _init_project() writes context.json with correct schema (keys: state, deferred_work, session_history)
• [ ] TEST-030-INTEG-003: _init_project() creates tests/__init__.py, tests/unit/__init__.py, tests/integration/__init__.py
• [ ] TEST-030-INTEG-004: _init_project() is idempotent — running twice on same directory does not raise and does not overwrite context.json
• [ ] TEST-030-INTEG-005: _git_commit() creates a git commit in the project_dir with expected message
• [ ] TEST-030-INTEG-006: _git_commit() is a no-op (no exception, no subprocess call) when .git directory absent

Design Doc Writing (3 tests)

• [ ] TEST-030-INTEG-007: _write_design_docs() writes exactly 5 .md files to {project_dir}/design/ when all content is non-empty
• [ ] TEST-030-INTEG-008: _write_design_docs() skips writing empty string sections (file not created)
• [ ] TEST-030-INTEG-009: _write_design_docs() produces readable UTF-8 content that matches design_docs values

Context Mixin (3 tests)

• [ ] TEST-030-INTEG-010: _build_monorepo_context() with no CapWords in requirements (e.g., "add a task") returns empty string without crashing
• [ ] TEST-030-INTEG-011: _scan_filesystem_for_classes() with a temp directory containing a Python file with a matching class definition populates loaded dict
• [ ] TEST-030-INTEG-012: _try_load_class_file() with a 300-line Python file truncates content to 200 lines with truncation marker

Compliance Tests (5)

Constitutional Verification

• [ ] TEST-030-COMPLIANCE-001: No unittest.mock, MagicMock, patch, or AsyncMock imported in any test file for orchestrata-architect — verify via source scan
• [ ] TEST-030-COMPLIANCE-002: U:Ar writes only within project_dir — _write_design_docs() in integration test asserts no files written outside temp dir
• [ ] TEST-030-COMPLIANCE-003: process() with unrecognized subject returns None (not exception, not empty CXP) — no silent swallowing of unknown traffic
• [ ] TEST-030-COMPLIANCE-004: _finalize_design() only returns implement CXP after _write_design_docs() succeeds — files exist on disk before packet constructed (integration test)
• [ ] TEST-030-COMPLIANCE-005: MAX_DESIGN_CYCLES forced escalation prints "[U:Ar] Max design cycles" in stdout — transparency requirement met

Test Execution

Running Tests

# Run all architect tests
ci/local-ci.sh test -- -k "architect"

# Run unit tests only
uv run pytest tests/test_architect_volk.py tests/test_architect_design.py tests/test_architect_fields.py -v

# Run integration tests
uv run pytest tests/test_architect_project.py tests/test_architect_context.py -v

# Run compliance tests
uv run pytest tests/test_architect_compliance.py -v

# Run with coverage
uv run pytest tests/test_architect*.py --cov=packages/orchestrata-architect/src --cov-report=term-missing

Coverage Targets

Summary

Last Updated: 2026-04-04 Version: 1.0.0 Maintained By: Mohamed

Other tracked files

• specs/030-architect-volk/README.md
• specs/030-architect-volk/compliance-audit.md

Full spec text

Verbatim from specs/030-architect-volk/spec.md; headings are pushed down two levels.

SPEC-030: Architect Volk (U:Ar)

Metadata

• Spec ID: 030-architect-volk
• Title: Architect Volk — Software Architecture & Project Scaffold Agent
• Author: Mohamed
• Status: Implemented
• Created: 2026-04-04
• Last Updated: 2026-04-04
• Priority: P0
• Components: ArchitectVolk, ArchitectContextMixin, ArchitectProjectMixin, context_builder, project_init, prompts
• Version: 1.0.0
• API Version: v1
• Compatibility: Python 3.14t, orchestrata-core >=0.7.0, orchestrata-agents >=0.7.0, Neo4j 5.x
• Package: orchestrata-architect (2,010 LOC, 9 files)
• Dependencies: orchestrata-core, orchestrata-agents, orchestrata-cxp, orchestrata-llm, orchestrata-knowledge

Overview

What

U:Ar is the Architect volk — the design authority in the Orchestrata pipeline. It receives validated requirements from U:PM (or UX artifacts from U:Ux) and produces five structured architecture artifacts: an architecture document, a file tree, an API spec, a class diagram, and a requirements document. It uses call_reasoner() — a reasoning-tier LLM (deepseek-reasoner or Claude Opus) — to perform deep architectural thinking via structured chain-of-thought decomposition. Designs are reviewed by J:Junior in an iterative feedback loop (up to MAX_DESIGN_CYCLES) before escalation to U:Cd (CodeDirector) for implementation.

Why

• Generated projects have no coherent architecture; files and responsibilities emerge ad-hoc
• Junior developers (J:Junior) need unambiguous contracts (signatures, types, data flow) to implement without guessing
• Without codebase context, the architect re-invents types and APIs that already exist
• Without a review loop, design mistakes cascade into implementation failures
• Without project scaffold, each project starts from zero with no standard structure

How

• U:PM sends scope_validated (or U:Ux sends ux_complete) CXP packet to U:Ar
• U:Ar queries Neo4j for existing monorepo types and project tree (ArchitectContextMixin)
• U:Ar calls call_reasoner() with ARCHITECT_PROMPT_TEMPLATE, injecting context
• LLM response is parsed into five sections: ARCHITECTURE, REQUIREMENTS, FILE_TREE, API_SPEC, CLASS_DIAGRAM
• Design docs written to {project_dir}/design/ and committed to git
• U:Ar sends design_review CXP to J:Junior; J:Junior responds with design_feedback
• If verdict == "READY" or design_cycles >= MAX_DESIGN_CYCLES, escalate to U:Cd
• Otherwise, iterate using ARCHITECT_UPDATE_TEMPLATE with J:Junior's questions
• U:Cd receives implement CXP with all five artifacts plus monorepo context

Terminology and Glossary

User Scenarios & Stories

US-001: Initial Architecture Generation (Critical)

As a system operator I want a complete architecture produced from requirements before any code is written So that J:Junior implements against a coherent design with unambiguous contracts

Acceptance Criteria:

• U:Ar receives scope_validated (or ux_complete / implement) CXP and initiates design
• call_reasoner() called with structured 5-step chain-of-thought prompt
• LLM response parsed into five sections: ARCHITECTURE, REQUIREMENTS, FILE_TREE, API_SPEC, CLASS_DIAGRAM
• All five sections written to {project_dir}/design/ as separate markdown files
• design_review CXP sent to J:Junior with all five artifacts and design cycle number
• Architecture doc includes Architecture Decision Records for non-obvious choices

US-002: Design Feedback Loop (Critical)

As a system operator I want J:Junior to review the design before implementation begins So that blocking ambiguities are resolved before code is written

Acceptance Criteria:

• U:Ar receives design_feedback CXP with verdict and questions list
• If verdict == "READY": escalate design to U:Cd via implement CXP
• If questions exist and cycles < MAX_DESIGN_CYCLES: call call_reasoner() with ARCHITECT_UPDATE_TEMPLATE
• Updated design docs written and committed after each iteration cycle
• design_cycles counter incremented on each iteration
• After MAX_DESIGN_CYCLES without "READY": escalate anyway with log warning

US-003: Monorepo Context Injection (Critical)

As a architect I want existing Orchestrata APIs and types visible during design So that designed systems use real constructors and import paths, not invented ones

Acceptance Criteria:

• CapWords class names extracted from requirements text via regex
• Neo4j queried for matching classes scoped to "orchestrata" project node
• Source files loaded (capped at 200 lines each) and injected into prompt
• Filesystem fallback scan used when Neo4j is unreachable
• Project tree (packages, modules, top classes/functions) queried from Neo4j
• Combined context injected as EXISTING API SOURCES section in prompt
• Brace-escaping applied before str.format() injection

US-004: Project Scaffold Creation (Critical)

As a developer I want a production-ready project directory created before code generation So that J:Junior has a clean workspace with proper structure from the start

Acceptance Criteria:

• Project directory created at {PROJECT_WORKSPACE_ROOT}/{slugified_name}
• Subdirectories created: design/, src/, tests/, tests/unit/, tests/integration/, docs/, requirements/
• __init__.py files created in tests/ directories
• context.json initialised with state/deferred_work/session_history structure
• Git repository initialised with git init
• UV virtual environment created with Python 3.14t (free-threaded)
• Design finalization commits all files with descriptive message

US-005: Design Escalation to CodeDirector (Critical)

As a system operator I want finalized design forwarded to U:Cd with all artifacts So that implementation can proceed with complete context

Acceptance Criteria:

• implement CXP sent to U:Cd with: architecture, requirements, file_tree, api_spec, class_diagram
• CXP also carries: original_intent, project_dir, task_summary, structured_requirements, user_stories, monorepo_src_section, nfrs, spec_metadata
• WorkStatus set to IN_PROGRESS on escalation
• Design docs git-committed before escalation with cycle count in message

US-006: UX Design Integration (High)

As an architect I want UX design artifacts incorporated into the architecture So that UI projects have their component hierarchy and workflows reflected in the file tree

Acceptance Criteria:

• ux_complete subject triggers same design flow as scope_validated
• ux_design payload field extracted from packet
• UX design injected as a labelled section in the architecture prompt
• Print confirmation when UX design is incorporated

US-007: Structured Requirements Propagation (High)

As a developer I want BA-structured requirements forwarded through the pipeline So that CodeDirector and Junior have typed requirements, not just prose

Acceptance Criteria:

• structured_requirements, user_stories, nfrs, spec_metadata extracted from incoming packet
• _impact_report from parameters field printed if present (classification, severity, affected files)
• All structured fields forwarded in finalization implement packet to U:Cd

US-008: Graceful Degradation (High)

As a system operator I want U:Ar to continue when Neo4j or uv is unavailable So that architecture generation does not block on infrastructure failures

Acceptance Criteria:

• Neo4j connection failure returns blank string (no crash, no block)
• Filesystem scan fallback activated when Neo4j returns no results
• Filesystem scan skipped if monorepo packages directory does not exist
• uv venv failure logged at DEBUG level, not propagated
• git init failure printed but not raised
• All Neo4j operations have try/except with debug-level logging

Standardized Acceptance Criteria

Functional Requirements

Non-Functional Requirements

Security Requirements

Authentication

• U:Ar requires valid CXP packet authentication via orchestrata-core infrastructure
• No additional authentication beyond base CXP protocol required
• All CXP packets validated by orchestrata-core before reaching U:Ar

Authorization

• U:Ar processes packets from whitelisted agents only: U:PM, U:Ux, J:Junior
• U:Ar sends packets to whitelisted agents only: J:Junior, U:Cd
• Packet routing validated in process() method before any processing

Input Validation

• All CXP packet payloads validated before access (type checking, null checks)
• Requirements text sanitized before LLM injection (no script injection)
• Neo4j queries parameterized to prevent injection attacks
• Project name slugification prevents directory traversal attacks

Audit Logging

• All CXP packet processing logged with trace_id
• Design decisions logged to git commits with cycle count
• Neo4j connection failures logged at DEBUG level
• LLM call latencies tracked for performance monitoring
• Security events logged at INFO level: invalid subjects, failed packet processing

Data Protection

• Project workspaces created with 0700 permissions (owner-only access)
• context.json files contain no secrets; only structured state data
• LLM prompts include only sanitized context; no API keys or credentials
• Source files from Neo4j truncated at 200 lines to prevent large data exposure

Secure Defaults

• Git commits fail safely if git not available (no secrets leaked)
• UV virtual environment creation fails safely (no runtime dependencies)
• Neo4j unavailable triggers graceful degradation, not failure
• All file operations use secure path joining (no path traversal)
• LLM context size capped at 100KB to prevent prompt injection

Technical Design

Pipeline Position

HUMAN → U:Cx → U:PM → (U:Ux if has_ui) → U:Ar → J:Junior → U:Ar → [feedback loop] → U:Cd → J:Junior (impl)
                           ↑ scope_validated / ux_complete
                           |
                     U:Ar design loop:
                       1. _handle_design() → design_review → J:Junior
                       2. J:Junior design_feedback → _handle_feedback()
                       3. If READY or max_cycles: _finalize_design() → U:Cd
                       4. Else: _iterate_design() → design_review → J:Junior

CXP Message Flow

Class Hierarchy

BaseVolk
    └── ArchitectVolk (also inherits ArchitectProjectMixin, ArchitectContextMixin)
            ├── alias = "U:Ar"
            ├── role = "Architect"
            ├── escalation_target = "U:Cd"
            ├── design_docs: dict[str, str]  (5 keys)
            ├── design_cycles: int
            ├── process() — router
            ├── _handle_design() — initial design
            ├── _handle_feedback() — feedback routing
            ├── _finalize_design() — escalation
            ├── _iterate_design() — design update
            └── _make_review_packet() — J:Junior packet builder

ArchitectContextMixin
    ├── _build_full_monorepo_context(requirements) → str
    ├── _build_project_tree_context() → str
    ├── _build_monorepo_context(text) → str
    ├── _scan_filesystem_for_classes(names, loaded) → None
    ├── _try_load_class_file(fpath, root, names, loaded) → None
    └── _slugify(text) → str

ArchitectProjectMixin
    ├── _init_project() → None
    ├── _write_context_json() → None
    ├── _git_init() → None
    ├── _create_venv() → None
    ├── _write_design_docs() → None
    ├── _parse_design(response) → None
    └── _git_commit(message) → None

File Structure

packages/orchestrata-architect/
├── pyproject.toml
└── src/orchestrata/volks/architect/
    ├── __init__.py           (re-exports ArchitectVolk)
    ├── volk.py               (ArchitectVolk — process, _handle_design, _handle_feedback, ...)
    ├── architect_context.py  (ArchitectContextMixin — Neo4j + filesystem context queries)
    ├── architect_project.py  (ArchitectProjectMixin — scaffold, doc writing, git)
    ├── architect_prompts.py  (ARCHITECT_PROMPT_TEMPLATE, ARCHITECT_UPDATE_TEMPLATE, MAX_DESIGN_CYCLES)
    ├── context_builder.py    (standalone context builder helpers)
    ├── project_init.py       (standalone project initialization helpers)
    ├── prompts.py            (additional prompt templates and CODING_STANDARDS import)
    └── volk_context.py       (graph directives and context extraction helpers)

Data Models

DesignDocuments Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DesignDocuments",
  "description": "Five architecture artifacts produced by U:Ar",
  "type": "object",
  "required": ["architecture", "requirements", "file_tree", "api_spec", "class_diagram"],
  "properties": {
    "architecture": {
      "type": "string",
      "description": "Component descriptions, responsibilities, ADRs, data flow",
      "minLength": 0
    },
    "requirements": {
      "type": "string",
      "description": "Numbered FR/NFR/ERR requirements list",
      "minLength": 0
    },
    "file_tree": {
      "type": "string",
      "description": "Exact flat file tree starting at src/ and tests/",
      "minLength": 0
    },
    "api_spec": {
      "type": "string",
      "description": "Per-module imports, classes, methods, functions with signatures",
      "minLength": 0
    },
    "class_diagram": {
      "type": "string",
      "description": "Mermaid or ASCII class diagram showing relationships",
      "minLength": 0
    }
  }
}

DesignReview CXP Payload (U:Ar → J:Junior)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DesignReviewPayload",
  "type": "object",
  "required": ["architecture", "requirements", "file_tree", "api_spec", "class_diagram", "design_cycle", "project_dir", "task_summary"],
  "properties": {
    "architecture": { "type": "string" },
    "requirements": { "type": "string" },
    "file_tree": { "type": "string" },
    "api_spec": { "type": "string" },
    "class_diagram": { "type": "string" },
    "design_cycle": { "type": "integer", "minimum": 1 },
    "project_dir": { "type": "string", "description": "Absolute path to project workspace" },
    "task_summary": { "type": "string" }
  }
}

DesignFeedback CXP Payload (J:Junior → U:Ar)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "DesignFeedbackPayload",
  "type": "object",
  "required": ["verdict"],
  "properties": {
    "verdict": {
      "type": "string",
      "enum": ["READY", "QUESTIONS"],
      "description": "READY = design approved; QUESTIONS = blocking ambiguities"
    },
    "questions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of blocking questions from J:Junior"
    },
    "design_cycle": {
      "type": "integer",
      "minimum": 1
    }
  }
}

ImplementEscalation CXP Payload (U:Ar → U:Cd)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ImplementEscalationPayload",
  "type": "object",
  "required": ["architecture", "requirements", "file_tree", "api_spec", "class_diagram", "project_dir", "task_summary"],
  "properties": {
    "architecture": { "type": "string" },
    "requirements": { "type": "string" },
    "file_tree": { "type": "string" },
    "api_spec": { "type": "string" },
    "class_diagram": { "type": "string" },
    "original_intent": { "type": "string" },
    "project_dir": { "type": "string" },
    "task_summary": { "type": "string" },
    "structured_requirements": { "type": "array" },
    "user_stories": { "type": "array" },
    "monorepo_src_section": { "type": "string" },
    "nfrs": { "type": "array" },
    "spec_metadata": { "type": "object" }
  }
}

Error Conditions and Edge Cases

Performance Benchmarks

Testing

Testability Guidelines

Dependencies and Environmental Assumptions

Runtime Dependencies

Environmental Assumptions

Governance

Ownership

• Spec Owner: Mohamed
• Implementation Owner: orchestrata-agents team
• Review Cadence: Monthly spec review against implementation
• Breaking Change Authority: Spec owner must approve any breaking changes

Lifecycle

• Status: Implemented
• Deprecation Policy: 2 minor version warning before removal
• Migration Path: Documented in release notes
• Rollback Plan: Git revert to previous version tag

Compliance

• All error conditions must have corresponding test coverage
• All functional requirements must have traceable implementation
• All public methods require Google-style docstrings
• No mocking in test files (real implementations only)
• Performance benchmarks must pass in CI pipeline

Standards Adherence

• Follows SPEC-097 Testing Standards
• Follows SPEC-098 API Standards
• Follows SPEC-000 CLI Standards
• Code style: Black formatter, isort import sorting
• Maximum class size: 300 lines
• Maximum file size: 500 lines

Review Process

• Self-review against SPEC_STANDARD.md before PR
• Adversarial review (find gaps) by another engineer
• Second-pass review for completeness
• Final approval by spec owner

Integration Points

Incoming Integrations

Outgoing Integrations

Knowledge Graph Integration

Filesystem Integration

LLM Integration

Examples and Sample Data

Example 1: Initial Design Request (U:PM → U:Ar)

{
  "header": {
    "from_agent": "U:PM",
    "to_agent": "U:Ar",
    "subject": "scope_validated",
    "thread_id": "thread-042"
  },
  "payload": {
    "task_summary": "Build a task management CLI with SQLite storage",
    "project_name": "taskman",
    "requirements": "1. Add tasks with name and due date\n2. List all tasks\n3. Mark tasks complete",
    "original_intent": "A simple task manager for personal use",
    "structured_requirements": ["Add task", "List tasks", "Complete task"],
    "user_stories": [],
    "nfrs": ["Response time < 200ms"],
    "spec_metadata": {},
    "scope_data": {"complexity_score": 0.3, "estimated_files": 5}
  }
}

Example 2: Design Feedback — QUESTIONS (J:Junior → U:Ar)

{
  "header": {
    "from_agent": "J:Junior",
    "to_agent": "U:Ar",
    "subject": "design_feedback",
    "thread_id": "thread-042"
  },
  "payload": {
    "verdict": "QUESTIONS",
    "design_cycle": 1,
    "questions": [
      "What is the exact SQLite schema for the tasks table?",
      "Should completed tasks be deleted or retained with a status flag?"
    ]
  }
}

Example 3: Design Feedback — READY (J:Junior → U:Ar)

{
  "header": {
    "from_agent": "J:Junior",
    "to_agent": "U:Ar",
    "subject": "design_feedback",
    "thread_id": "thread-042"
  },
  "payload": {
    "verdict": "READY",
    "design_cycle": 2,
    "questions": []
  }
}

Example 4: Escalation to U:Cd (U:Ar → U:Cd)

{
  "header": {
    "from_agent": "U:Ar",
    "to_agent": "U:Cd",
    "subject": "implement",
    "thread_id": "thread-042"
  },
  "payload": {
    "architecture": "## Components\n1. CLI (typer) ...\n2. Storage (sqlite3) ...",
    "requirements": "FUNCTIONAL:\n1. FR-01: Add task ...",
    "file_tree": "src/\n├── taskman/\n│   ├── __init__.py\n│   ├── cli.py\n│   └── storage.py\ntests/\n└── test_cli.py",
    "api_spec": "Module: src/taskman/storage.py\nClasses:\n  TaskStore:\n    Methods:\n      add_task(name: str, due: str) -> int ...",
    "class_diagram": "classDiagram\n  CLI --> TaskStore\n  TaskStore --> Task",
    "project_dir": "/opt/orchestrata-workspaces/taskman",
    "task_summary": "Build a task management CLI with SQLite storage",
    "original_intent": "A simple task manager for personal use",
    "structured_requirements": ["Add task", "List tasks", "Complete task"],
    "user_stories": [],
    "monorepo_src_section": "",
    "nfrs": ["Response time < 200ms"],
    "spec_metadata": {}
  }
}

API Contracts

Architect Volk Service Interface

service: ArchitectVolk
version: "1.0.0"
agent_id: "U:Ar"
alias: "U:Ar"
role: "Architect"
escalation_target: "U:Cd"

inbound_subjects:
  - implement
  - scope_validated
  - ux_complete
  - design_feedback

outbound_subjects:
  - design_review     # to J:Junior
  - implement         # to U:Cd

design_artifacts:
  - architecture      # ARCHITECTURE: section
  - requirements      # REQUIREMENTS: section
  - file_tree         # FILE_TREE: section
  - api_spec          # API_SPEC: section
  - class_diagram     # CLASS_DIAGRAM: section

llm_tier: reasoning   # call_reasoner() — deepseek-reasoner or opus
max_design_cycles: 99 # configurable in architect_prompts.py

API Versioning Metadata

Observability Requirements

Structured Logging

Success Criteria

Visual Architecture

Class Diagram

Diagram source shown as text: Mermaid could not parse it (Error: Parse error on line 15:).

classDiagram-direction LR
    class ArchitectAgent {
        $agent_type: ClassVar[str] = 'U:Ar'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async analyze_impact(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_solution(requirements: dict[str, Any]): dict[str, Any]
        +async review_architecture(architecture: dict[str, Any]): dict[str, Any]
    }
    class BaseAgent <<pydantic>> {
        -model: str = Field(default='claude-3-5-haiku', description='Model identifier for the agent', min_length=1, strict=True)
        -agent_id: str = Field(default='', description='Unique agent identifier', strict=True)
        -agent_name: str = Field(default='', description='Human-readable agent name', strict=True)
        $agent_type: ClassVar[str] = 'U:Base'
        $_instance_counters: ClassVar[dict[str, int]] = {}
        ---
        {@classmethod} +validate_model(v: str): str
        +__init__(**data: Any): None
        #_generate_unique_id(): str
        +model_post_init(__context: Any): None
        +async receive_message(message: Any, sender: str | None = None): Any
    }
    class CodeDirectorAgent {
        $agent_type: ClassVar[str] = 'U:Cd'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async execute_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async review_code(code: str, requirements: dict[str, Any]): dict[str, Any]
        +async implement_feature(spec: dict[str, Any]): dict[str, Any]
    }
    class QualityAssuranceAgent {
        $agent_type: ClassVar[str] = 'U:Qa'
        ---
        +__init__(model: str = 'claude-3-5-sonnet', agent_name: str = '')
        +async review_edit(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async run_tests(test_suite: str): dict[str, Any]
        +async audit_security(code: str): dict[str, Any]
    }
    class UserExperienceAgent {
        $agent_type: ClassVar[str] = 'U:Ux'
        ---
        +__init__(model: str = 'claude-3-5-haiku', agent_name: str = '')
        +async review_ux(file_path: str, old_string: str, new_string: str, context: dict[str, Any] | None = None): dict[str, Any]
        +async design_ui(requirements: dict[str, Any]): dict[str, Any]
        +async evaluate_accessibility(ui: dict[str, Any]): dict[str, Any]
    }
    BaseAgent <|-- ArchitectAgent
    BaseModel <|-- BaseAgent
    BaseAgent <|-- CodeDirectorAgent
    BaseAgent <|-- QualityAssuranceAgent
    BaseAgent <|-- UserExperienceAgent

Revision History

Related

• RTM page for 030-architect-volk
• All specs
• RTM overview
• Gates