Skip to content

LiorCohen/sdd / plugin/core/skills/project-settings

project-settings

Verified

Manage project settings in sdd/sdd-settings.yaml including component settings that drive scaffolding.

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

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

Output

Schema: 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 (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

AspectSettingsConfig
WhatStructural capabilitiesRuntime values
When setAt component creation, changeablePer-environment
Examplesdepends_on, component-type-specific fieldsport: 3000, replicas: 3
AffectsWhat gets scaffoldedValues in scaffolded files
Stored insdd/sdd-settings.yamlConfig 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:

ParameterRequiredDescription
initialized_by_plugin_versionYesCurrent SDD plugin version
project_nameYesProject name
project_descriptionNoProject description
componentsYesList 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

  • Names must be lowercase
  • Use hyphens, not underscores
  • No spaces allowed
  • Names should be multi-word and domain-specific
    • Good: order-service, analytics-db, customer-portal, task-api
    • Avoid: api, public, primary, main, server
  • Exception: config (singleton)

Minimal Template

Template for initializing a new sdd/sdd-settings.yaml:

# ============================================================================
# SDD PROJECT SETTINGS - DO NOT EDIT MANUALLY
# ============================================================================
# This file is generated and maintained by SDD commands.
# To modify settings, use: /sdd with natural language about settings
# ============================================================================

sdd:
  initialized_by_plugin_version: "{{PLUGIN_VERSION}}"
  updated_by_plugin_version: "{{PLUGIN_VERSION}}"
  initialized_at: "{{CURRENT_UTC_DATETIME}}"
  updated_at: "{{CURRENT_UTC_DATETIME}}"

project:
  name: "{{PROJECT_NAME}}"

# Tech packs and components are added here during init and implementation.

techpacks:
  <namespace>:
    name: <tech-pack-name>
    namespace: <namespace>
    version: "1.0.0"
    mode: internal
    path: <tech-pack-directory>

components:
  my-component:
    type: <type-from-tech-pack>
    techpack: <namespace>
    directory: <directory-from-tech-pack-pattern>
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall