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.

| Layer | Files Generated | Purpose | |-------|----------------|---------| | control | .control/policy.yaml, commands.yaml, topology.yaml | Governance gates, command registry, repo topology | | harness | scripts/harness/*.sh (9 scripts), Makefile.control, .github/workflows/ci.yml | Build automation, git hooks, CI | | knowledge | docs/_index.md, docs/_templates/ (5), docs/glossary.md, architecture docs, ADRs, runbooks | Obsidian knowledge graph skeleton | | consciousness | CLAUDE.md, AGENTS.md | AI agent instructions — metalayer-aware, safety-guardrailed | | autoany | .control/egri.yaml | EGRI self-improvement loop config |

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:

| Script | Purpose | Timeout | |--------|---------|---------| | smoke.sh | Install + check + build main app | ~120s | | check.sh | Lint + typecheck | ~60s | | ci.sh | Full pipeline: check + test + build | ~600s | | check-policy.sh | Advisory policy gate warnings for staged files | — | | check-docs-freshness.sh | Verify all docs referenced in _index.md | ~10s | | check-wikilinks.sh | Validate [[wikilinks]] resolve to real files | ~10s | | audit.sh | Entropy audit: topology, stale docs, wikilinks | — | | install-hooks.sh | Install pre-commit git hook | — | | pre-commit.sh | Fast hook: lint staged TS + docs check | ` 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: broomva
• Source: broomva/symphony-forge
• License: Apache-2.0
• Homepage: https://skills.sh

Install and usage instructions live in the source repository linked above.