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

Layer System — Complete Reference

Architecture

Each layer is a TypeScript module implementing the Layer interface:

interface Layer {
  name: string;
  description: string;
  dependsOn?: string[];  // soft dependencies — adjusts content, not required
  generate: (config: ProjectConfig) => FileEntry[];
  postInstall?: (config: ProjectConfig, projectDir: string) => Promise<void>;
}

Templates are inline TypeScript template literals — no separate template files. This ensures tsup bundles everything into a single dist/index.js.

ProjectConfig

interface ProjectConfig {
  name: string;
  description: string;
  packageManager: "bun" | "npm" | "yarn" | "pnpm";
  layers: string[];
}

The layers array determines which layers are active. The consciousness layer reads this to conditionally generate content — sections for uninstalled layers include callout warnings.

Layer Dependency Graph

control ──→ harness
   │           │
   └──→ knowledge
   │           │
   └──→ autoany
            │
consciousness (reads all)

Dependencies are soft — installing consciousness alone works, but the generated CLAUDE.md will include "install X layer" callouts for missing layers.

File Generation

Each layer's generate() method returns FileEntry[]:

interface FileEntry {
  path: string;      // relative to project root
  content: string;   // file content
  executable?: boolean;  // chmod +x (for bash scripts)
}

The scaffold system writes these files, creates directories as needed, and records installed layers in .symphony-forge.json.

Control Layer — Generated Files

.control/policy.yaml

Risk gates with:

• triggers: file glob patterns that activate the policy
• requires: checks that must pass
• risk: low | medium | high | critical
• rollback: how to undo

.control/commands.yaml

Command registry mapping harness scripts:

• script: path to executable
• timeout: max seconds
• usage: make command
• when: recommended context

.control/topology.yaml

Repository map:

• Apps with ports, risk levels, domains, dependencies
• Packages with paths and domains
• Knowledge entry points

Harness Layer — Generated Files

9 bash scripts following these conventions:

• #!/usr/bin/env bash + set -euo pipefail
• REPO_ROOT resolution via BASH_SOURCE
• Package-manager-agnostic commands via template helpers
• Consistent echo format: [step/total] Description...

Plus:

• Makefile.control with .PHONY targets and help text
• .github/workflows/ci.yml for GitHub Actions

Knowledge Layer — Generated Files

Obsidian-flavored Markdown with:

• YAML frontmatter (title, type, domain, status, tags)
• Wikilinks: [[path/to/doc]] → docs/path/to/doc.md
• Callouts: > [!decision], > [!warning], > [!context]
• Mermaid diagrams in fenced code blocks

Consciousness Layer — Generated Files

CLAUDE.md and AGENTS.md that:

• Reference the correct package manager throughout
• Include/exclude sections based on installed layers
• Follow the metalayer pattern (read policy → traverse docs → check → implement → update docs → run checks)

AutoAny Layer — Generated Files

EGRI config with:

• Evaluators (blocking: build, typecheck, tests; non-blocking: audit)
• Mutable surfaces with constraints
• Immutable surfaces (protected files)
• Ranking strategy and promotion criteria

The Control Metalayer Pattern

What Is It?

The control metalayer is a governance layer for software development — a set of declarative YAML files, automation scripts, interconnected documentation, and agent instructions that together form a control system applied to the development process itself.

Control Systems Analogy

The metalayer maps directly to control theory:

Why It Works

1. Declarative governance — Policies are data (YAML), not code. Easy to read, modify, and audit. 2. Self-describing — The topology map and knowledge graph mean agents (human or AI) can discover conventions without tribal knowledge. 3. Measurable entropy — The audit script quantifies drift: uncovered topology, stale docs, broken links. Entropy is a number you can trend. 4. Composable — Each layer works independently. You can start with just control and add layers as the project matures. 5. Agent-native — The consciousness layer generates instructions that teach AI agents to operate within the governance framework, creating a closed loop between human intent and autonomous execution.

The Five Layers

┌─────────────────────────────────────────────┐
│  consciousness (CLAUDE.md, AGENTS.md)       │ ← Agent interface
├─────────────────────────────────────────────┤
│  autoany (.control/egri.yaml)               │ ← Self-improvement
├─────────────────────────────────────────────┤
│  knowledge (docs/)                          │ ← System model
├─────────────────────────────────────────────┤
│  harness (scripts/harness/, Makefile)       │ ← Actuators
├─────────────────────────────────────────────┤
│  control (.control/*.yaml)                  │ ← Sensors + setpoints
└─────────────────────────────────────────────┘

Adoption Path

1. Start small — npx symphony-forge layer control to add governance gates 2. Automate — npx symphony-forge layer harness for scripts and CI 3. Document — npx symphony-forge layer knowledge for the docs skeleton 4. Enable agents — npx symphony-forge layer consciousness for CLAUDE.md/AGENTS.md 5. Self-improve — npx symphony-forge layer autoany for EGRI loops

Anti-Patterns

• Don't over-govern — Start with policies for genuinely high-risk operations. Add more as needed.
• Don't let docs rot — The audit script catches stale docs. Run it regularly.
• Don't skip the audit — If the audit fails, fix it before shipping. Entropy compounds.
• Don't fight the layers — If a generated file doesn't fit, modify it. The metalayer is a starting point, not a straitjacket.

Creating and Publishing Agent Skills

What Is a Skill?

A skill is a reusable package of domain knowledge and instructions for AI coding agents. Skills follow the Agent Skills specification and can be installed via the skills.sh registry.

Skill Structure

my-skill/
  SKILL.md              # Required — YAML frontmatter + markdown instructions
  references/           # Optional — detailed docs loaded on-demand
    setup.md
    api.md
  scripts/              # Optional — executable automation
    validate.sh
  assets/               # Optional — templates, images
    template.tsx

Writing SKILL.md

Frontmatter (Required)

---
name: my-skill
description: Expert assistance for [domain]. Triggers on [activation context].
---

The description field is the primary triggering mechanism — Claude reads descriptions to decide when to activate a skill. Make it specific about what triggers the skill.

Body (Required)

The markdown body contains: 1. Overview — What the skill does, in 2-3 sentences 2. Quick Start — Most common commands/workflows 3. Key Concepts — Domain knowledge the agent needs 4. Common Tasks — Step-by-step procedures 5. Reference pointers — See references/setup.md for on-demand loading

Size Guidelines

• SKILL.md body: < 5,000 words (loaded when skill triggers)
• Reference files: unlimited (loaded on-demand)
• Keep SKILL.md focused on the 80% case; put detailed docs in references

Progressive Disclosure

Skills use three-level loading:

1. Metadata (~100 words) — Name + description, always in context 2. SKILL.md body (<5k words) — Loaded when skill triggers 3. References (unlimited) — Loaded as-needed by the agent

This means you can include extensive documentation without bloating every conversation.

Publishing to skills.sh

1. Initialize

npx skills init my-skill

This creates the skill directory structure and metadata.

2. Write your skill

Follow the SKILL.md format above. Add references as needed.

3. Test locally

Place the skill in your project's skills/ directory or in ~/.claude/skills/ for global access. Test by asking Claude questions that should trigger the skill.

4. Publish

Skills live in GitHub repositories. The skills.sh registry indexes them:

# Users install your skill via:
npx skills add your-github-user/your-repo@my-skill

Best Practices

1. Be specific in descriptions — "Expert assistance for Next.js App Router migration from pages/" is better than "Helps with Next.js" 2. Include code examples — Agents learn from examples more than abstract descriptions 3. Use references for depth — Keep SKILL.md scannable, put details in references 4. Test trigger accuracy — Verify the skill activates when expected and doesn't activate spuriously 5. Version your references — Update references when your tool/API changes 6. Include common errors — Agents benefit from knowing what goes wrong and how to fix it

Symphony Forge + Skills

Projects scaffolded with symphony-forge are skill-ready:

• The skills/ directory is gitignored by default for user-specific skills
• Project-level skills can be committed for team-shared knowledge
• The consciousness layer generates CLAUDE.md that instructs agents to check for available skills
• The knowledge layer's docs/ directory can serve as reference material for project-specific skills

Example: Creating a Skill for Your API

---
name: my-api
description: Expert assistance for the MyProject REST API. Triggers on questions about API endpoints, authentication, request/response schemas, error handling, and webhook integration.
---

# MyProject API

## Authentication
All requests require a Bearer token in the Authorization header.

## Endpoints

### POST /api/v1/users
Create a new user.

\`\`\`typescript
const response = await fetch('/api/v1/users', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({ email, name })
});
\`\`\`

## Common Errors

| Code | Meaning | Fix |
|------|---------|-----|
| 401 | Invalid token | Regenerate API key |
| 429 | Rate limited | Wait 60s, implement backoff |