Symphony Forge

symphony-forge

symphony-forge is a CLI tool that extends next-forge (the production-grade Turborepo template) with a composable control metalayer — governance gates, build automation, knowledge graphs, and AI agent instructions that make projects autonomous-agent-ready from day one.

Quick Start

Initialize a new project (next-forge + all layers)

npx symphony-forge init my-project

Add layers to an existing project

npx symphony-forge layer all        # Add all 5 layers
npx symphony-forge layer control    # Just governance gates
npx symphony-forge layer harness    # Just build automation
npx symphony-forge layer knowledge  # Just docs skeleton
npx symphony-forge layer consciousness  # Just CLAUDE.md + AGENTS.md
npx symphony-forge layer autoany    # Just EGRI config

Run entropy audit

npx symphony-forge audit

Layer System

symphony-forge uses a composable layer architecture. Each layer generates files into your project. Layers have soft dependencies — they adjust content based on what's installed but work independently.

What Each Layer Does

Control Layer

The control layer creates .control/ YAML files that define your project's governance:

• policy.yaml — Risk gates for database migrations (HIGH), dependency updates (MEDIUM), env variable changes (HIGH), new packages (MEDIUM), production deploys (CRITICAL). Each policy specifies triggers (file patterns), required checks, and rollback procedures.
• commands.yaml — Canonical command definitions mapping to harness scripts. Each command has a description, script path, timeout, usage pattern, and recommended context.
• topology.yaml — Full repo map listing all apps and packages with paths, descriptions, ports, risk levels, domains, and dependencies.

Harness Layer

Generates 9 executable bash scripts + Makefile + CI workflow:

All scripts use set -euo pipefail, REPO_ROOT resolution, and are parameterized for your package manager (bun/npm/yarn/pnpm).

The Makefile.control provides make -f Makefile.control <target> for all commands. The CI workflow runs check → test → build on push/PR.

Knowledge Layer

Creates an Obsidian-flavored Markdown knowledge graph:

• docs/_index.md — Entry point with Mermaid graph map, tag taxonomy, traversal instructions
• docs/glossary.md — Key terminology definitions
• docs/architecture/overview.md — System architecture with Mermaid diagrams
• docs/decisions/adr-001-metalayer.md — ADR explaining the control metalayer choice
• docs/runbooks/local-dev-setup.md — Getting started runbook
• docs/_templates/ — 5 templates (ADR, architecture, runbook, API contract, schema)

Documents use frontmatter tags (domain/, status/, type/) and wikilinks ([[architecture/overview]]).

Consciousness Layer (Key Differentiator)

Generates CLAUDE.md and AGENTS.md that are metalayer-aware:

• Content is conditional on installed layers — sections for uninstalled layers include callout warnings suggesting installation
• References correct package manager commands throughout
• Includes working protocol, constraints, knowledge graph traversal, and pre-push checklists
• Instructions tell agents to read policy.yaml, traverse docs/_index.md, run Makefile.control checks, and follow EGRI loops

AutoAny Layer (EGRI)

Generates .control/egri.yaml defining the Evaluate → Generate → Rank → Integrate self-improvement loop:

• Mutable surfaces — What the system can change (scripts, docs, control config, agent instructions) with constraints
• Immutable surfaces — Protected files (schema, env, lockfile)
• Evaluators — Blocking (build, typecheck, tests) and non-blocking (audit) checks
• Ranking — Strategy for comparing before/after states
• Promotion — Criteria and method for accepting changes

Manifest Tracking

symphony-forge creates .symphony-forge.json in your project root, tracking:

• Which layers are installed
• Package manager
• Creation and update timestamps

This enables smart layer additions (detects conflicts) and future update --layers support.

Creating Skills for Your Project

symphony-forge projects are skill-ready. To create a custom skill for your project:

1. Create the skill directory

mkdir -p skills/my-skill/references

2. Write SKILL.md

---
name: my-skill
description: Expert assistance for [your domain]. Triggers on [what activates it].
---

# my-skill

[Instructions for the agent when this skill activates]

## Key concepts
[Domain knowledge the agent needs]

## Common tasks
[Step-by-step procedures]

3. Add references (optional)

Place detailed documentation in references/ — agents load these on-demand without bloating the initial context.

4. Register with skills.sh

npx skills init my-skill     # Initialize metadata
npx skills publish            # Publish to skills.sh registry

For detailed layer contents and architecture, see:

• references/layers.md — Complete layer system documentation
• references/metalayer-pattern.md — The control metalayer design pattern
• references/skill-creation.md — Full guide to creating and publishing agent skills