---
name: arrangement
type: type
status: draft
version: 1.0.0
description: Specification for the Arrangement file, which bridges a Score (spec) to a specific Build Environment.
---

# 1. Overview

An **Arrangement** file acts as the 'makefile' for SpecSoloist. It defines how a high-level Score (specification) should be realized in a specific physical environment. While the Score defines *what* to build, the Arrangement defines *how* and *where* to build it.

The Arrangement bridges the gap between language-agnostic requirements and language-specific implementation details, tools, and constraints. It is typically generated by the **Conductor** or provided by the user to tell the **Soloist** exactly how to realize the Score.

# 2. Schema

```yaml:schema
properties:
  target_language:
    type: string
    description: The programming language to use for implementation (e.g., python, typescript, rust).
  
  output_paths:
    type: object
    properties:
      implementation:
        type: string
        description: Relative path where the source code should be generated.
      tests:
        type: string
        description: Relative path where the tests should be generated.
    required:
      - implementation
      - tests

  environment:
    type: object
    properties:
      tools:
        type: array
        items:
          type: string
        description: List of required CLI tools (e.g., uv, ruff, pytest, npm, tsc).
      setup_commands:
        type: array
        items:
          type: string
        description: Commands to run to prepare the environment before building.

  build_commands:
    type: object
    properties:
      compile:
        type: string
        description: Command to compile the code (if applicable).
      lint:
        type: string
        description: Command to lint the generated code.
      test:
        type: string
        description: Command to run the generated tests.
    required:
      - test

  constraints:
    type: array
    items:
      type: string
    description: Non-functional constraints for the Soloist to follow during generation.
```

# 3. File Format

The Arrangement file can be persisted in two formats:
1. **YAML**: A standalone `.yaml` file (e.g., `arrangement.yaml`).
2. **Markdown**: A `.md` file with the configuration in a YAML frontmatter or a fenced code block (e.g., `arrangement.md`).

# 4. Constraints

- [NFR-01]: Paths in `output_paths` should be relative to the project root.
- [NFR-02]: `build_commands` must be executable in the shell of the target environment.
- [NFR-03]: `target_language` must be a lowercase identifier.
- [NFR-04]: If a command is not applicable for a language (e.g., `compile` for Python), it should be an empty string or a comment.

# 5. Examples

## 5.1 Python Project Arrangement

```yaml
target_language: python
output_paths:
  implementation: src/math_utils.py
  tests: tests/test_math_utils.py
environment:
  tools:
    - uv
    - ruff
    - pytest
  setup_commands:
    - uv sync
build_commands:
  compile: ""
  lint: uv run ruff check .
  test: uv run pytest
constraints:
  - Must pass ruff with 0 errors
  - Must use type hints for all function signatures
  - Must use google-style docstrings
```

## 5.2 TypeScript Project Arrangement

```yaml
target_language: typescript
output_paths:
  implementation: src/calculator.ts
  tests: tests/calculator.test.ts
environment:
  tools:
    - npm
    - jest
  setup_commands:
    - npm install
build_commands:
  compile: npx tsc
  lint: npx eslint src/**/*.ts
  test: npm test
constraints:
  - Must follow strict TypeScript mode
  - Must use ES6 modules
```