/project-settings

name: project-settings
description: Manage project settings in sdd/sdd-settings.yaml including component settings that drive scaffolding.
user-invocable: false

Project Settings

Single source of truth for the `sdd/sdd-settings.yaml` schema, component settings, validation rules, and directory mappings. Component types and their settings schemas are defined by the active tech pack — invoke `techpacks.listComponents` and `techpacks.routeSkills` rather than hardcoding type-specific knowledge.

---

Input

Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)

Accepts operation type and operation-specific parameters for managing sdd-settings.yaml.

Output

Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)

Returns success status, file path, and current component configurations.

Purpose

Manage the `sdd/sdd-settings.yaml` file that stores project configuration and component settings. Component settings are structural decisions that drive scaffolding, config initialization, and deployment.

File Location

Settings file: `sdd/sdd-settings.yaml` (git-tracked)

The `sdd/` directory contains all SDD metadata. Create this directory if it doesn't exist.

Migration from Legacy Location

If `sdd-settings.yaml` exists at project root (legacy location): 1. Create `sdd/` directory 2. Move `sdd-settings.yaml` to `sdd/sdd-settings.yaml` 3. Delete the root file 4. Commit the change

Quick migration command:

mkdir -p sdd && mv sdd-settings.yaml sdd/ && git add -A && git commit -m "Migrate sdd-settings.yaml to sdd/"

Schema

**Formal definition:** [`schemas/sdd-settings.schema.json`](./schemas/sdd-settings.schema.json) (JSON Schema Draft 2020-12)

The schema defines three top-level sections: `sdd` (plugin metadata), `project` (project metadata), and `components` (list of typed components with settings). Component types and their settings schemas are defined by the active tech pack.

Example

sdd:
  initialized_by_plugin_version: "7.0.0"
  updated_by_plugin_version: "7.1.0"
  initialized_at: "2026-02-07 00:00:00Z"
  updated_at: "2026-02-09 14:30:00Z"

project:
  name: "my-app"
  description: "A task management SaaS application"

techpacks:
  <namespace>:
    name: <tech-pack-name>
    namespace: <namespace>
    version: "1.0.0"
    mode: internal  # or external, git
    path: <tech-pack-directory>

components:
  my-component:
    type: <type-from-tech-pack>
    techpack: <namespace>
    directory: <directory-from-tech-pack-pattern>

  other-component:
    type: <type-from-tech-pack>
    techpack: <namespace>
    directory: <directory-from-tech-pack-pattern>

Settings vs Config

| Aspect | Settings | Config | |--------|----------|--------| | **What** | Structural capabilities | Runtime values | | **When set** | At component creation, changeable | Per-environment | | **Examples** | `depends_on`, component-type-specific fields | `port: 3000`, `replicas: 3` | | **Affects** | What gets scaffolded | Values in scaffolded files | | **Stored in** | `sdd/sdd-settings.yaml` | Config component `envs/` directory |

Component Settings

Component types and their settings schemas are defined by the active tech pack. Core does not hardcode component type definitions.

To discover available component types and their settings schemas:

Invoke techpacks.listComponents for the active tech pack namespace.

To load type-specific settings schemas during validation:

Invoke techpacks.routeSkills with:
  namespace: <active-namespace>
  phase: implementation

The tech pack's `techpack-settings` skill contains the full component type definitions, settings tables per type, directory patterns, and validation rules.

Directory Structure

Component directory patterns are defined in the tech pack manifest under `components.<type>.directory_pattern`. Invoke `techpacks.listComponents` to get the directory pattern for each component type. Do NOT hardcode type→directory mappings.

Validation Rules

• **Config mandatory singleton**: Every project must have exactly one config component (if the tech pack defines a `config` component type)
• **Component references**: Cross-references between components (e.g., `depends_on`) must reference existing component instances
• **Tech-pack-specific validation**: Additional validation rules are provided by the tech pack. Invoke `techpacks.routeSkills(phase: implementation)` for component-type-specific settings schemas.

Operations

Operation: `create`

Initialize a new settings file.

**Input:**

| Parameter | Required | Description | |-----------|----------|-------------| | `initialized_by_plugin_version` | Yes | Current SDD plugin version | | `project_name` | Yes | Project name | | `project_description` | No | Project description | | `components` | Yes | List of components with settings |

Operation: `read`

Load and return current settings.

Operation: `update`

Merge partial updates into existing settings. Triggers automatic sync of affected artifacts.

Operation: `get_component_dirs`

Get the actual directory names for all components.

Settings Lifecycle

┌─────────────────┐
│   /sdd (init)   │  Settings defined during project creation
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Scaffolding    │  Settings drive what files/templates are created
│  (initial)      │  Settings drive initial config values
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Development    │  Settings changes come from:
│                 │  - Specs (new components, capability changes)
│                 │  - Plans (implementation decisions)
│                 │  - /sdd with natural language about settings (manual adjustments)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Settings Sync  │  Changes propagate to affected artifacts
│  (incremental)  │  Only adds/updates, never deletes user content
└─────────────────┘

Naming Rules