hnidboubker symphony-orchestrator
symphony-orchestrator is the TOP-LEVEL ORCHESTRATOR of the entire development workflow.
It coordinates specialized skills but does not replace their responsibilities.
Objective
symphony-orchestrator orchestrates the complete development lifecycle:
Change
↓
Tests
↓
Commit
↓
Push
↓
Release
↓
Documentation
↓
Detect new changes
↓
Repeat only if necessary
↓
STOP
The specialized skills are:
commit-asynctests-asynctdd-asyncbdd-asyncauto-releasereadme-async
symphony-orchestrator is the only skill responsible for coordinating the complete workflow.
Required Structure
Create or update:
symphony-orchestrator/
├── references/
│ └── Context.md
├── scripts/
│ ├── install.sh
│ ├── install.ps1
│ └── install.py
├── SKILL.md
└── README.md
Before modifying anything:
- Inspect the repository.
- Inspect all existing skills.
- Read their SKILL.md files.
- Understand their contracts.
- Do not duplicate their responsibilities.
- Do not modify unrelated skills unless strictly necessary.
Core Architecture
The architecture is:
symphony-orchestrator
│
▼
tests-async
/ \
▼ ▼
tdd-async bdd-async
\ /
▼ ▼
TUnit
│
▼
PASS / FAIL
│
PASS only
▼
commit-async
│
▼
PUSH
│
▼
auto-release
│
▼
readme-async
│
▼
Change Detection
│
┌─────────┴─────────┐
│ │
NO CHANGES CHANGES
│ │
▼ ▼
STOP RESTART
The workflow is a controlled cascade.
Important Principle
Each skill has ONE responsibility.
symphony-orchestrator orchestrates.
tests-async orchestrates testing.
tdd-async performs TDD.
bdd-async performs BDD.
commit-async handles commit creation and approval.
auto-release handles semantic versioning, changelog generation, and Git tags.
readme-async handles README synchronization.
Do not duplicate these responsibilities inside symphony-orchestrator.
Workflow
The standard workflow is:
- Detect changes.
- Determine what kind of work is present.
- Select the appropriate testing strategy.
- Run
tests-async. - Stop if tests fail.
- Invoke
commit-async. - Wait for commit approval.
- Wait for push approval.
- Push the commit.
- Invoke
auto-release. - Create the release if required.
- Invoke
readme-async. - Detect whether new changes were created.
- If there are no new changes, stop.
- If new changes exist, evaluate them again.
- Prevent infinite loops.
Step 1 — Initial Change Detection
Start with:
git status --short
If there are no relevant changes:
return:
SYMPHONY_NO_CHANGES
Do not start the pipeline.
Never invent work.
Step 2 — Understand the Change
Inspect:
git status
git diff
git diff --cached
Understand:
- changed files;
- added files;
- deleted files;
- modified files;
- new functionality;
- bug fixes;
- refactoring;
- documentation changes;
- tests;
- configuration;
- breaking changes.
Do not modify files during analysis unless a delegated skill explicitly requires it.
Step 3 — Select Test Strategy
Delegate testing to:
tests-async
tests-async decides whether to use:
tdd-async
or:
bdd-async
based on the task.
Explicit user intent has priority.
If the user explicitly requests:
TDD
use TDD.
If the user explicitly requests:
BDD
use BDD.
If the user requests both:
BDD ↓ TDD
Use BDD to establish business behavior and TDD to drive implementation.
Do not duplicate test logic unnecessarily.
Step 4 — Test Gate
Invoke:
tests-async
Wait for its result.
Possible results:
TESTS_PASSED
TESTS_FAILED
TESTS_BLOCKED
TESTS_NOT_REQUIRED
If:
TESTS_FAILED
STOP.
Do not commit.
Do not push.
Do not release.
Return:
SYMPHONY_TESTS_FAILED
If:
TESTS_BLOCKED
STOP.
Return:
SYMPHONY_TESTS_BLOCKED
If:
TESTS_PASSED
continue.
Step 5 — Commit
Invoke:
commit-async
commit-async is responsible for:
- detecting changes;
- analyzing changes;
- proposing a Conventional Commit;
- asking the user for approval;
- creating the commit;
- asking for push approval;
- pushing the commit.
symphony-orchestrator must NOT bypass these approvals.
Do not create commits directly.
Do not automatically approve a commit.
Do not automatically push.
Wait for the result from commit-async.
Possible results:
COMMIT_CREATED
PUSH_COMPLETED
COMMIT_REJECTED
PUSH_REJECTED
COMMIT_FAILED
PUSH_FAILED
NO_CHANGES
Commit Rejection
If the user rejects the commit:
STOP.
Return:
SYMPHONY_COMMIT_REJECTED
Do not continue to release.
Push Rejection
If the user rejects the push:
STOP.
Do not release a commit that has not been pushed unless the user explicitly requests a local release.
Return:
SYMPHONY_PUSH_REJECTED
Step 6 — Release
After a successful push, invoke:
auto-release
auto-release must:
- inspect commits since the last release;
- determine whether a release is required;
- calculate semantic version;
- update CHANGELOG.md;
- create the Git tag;
- return the release result.
symphony-orchestrator must not calculate versions itself.
Do not use npm.
Do not use Node.js.
Do not use semantic-release.
Release Result
Possible results:
NO_RELEASE
RELEASE_CREATED
RELEASE_BLOCKED
RELEASE_FAILED
CHANGELOG_UPDATED
TAG_CREATED
If:
RELEASE_FAILED
STOP and report the failure.
If:
NO_RELEASE
continue to readme-async if documentation synchronization is relevant.
If:
RELEASE_CREATED
continue to readme-async.
Tag Pushing
Do not force-push tags.
Never execute:
git push --force
Never delete or replace an existing release tag.
If auto-release creates a local tag that must be pushed, follow the release skill's explicit approval contract.
Never silently push release tags.
Step 7 — README
Invoke:
readme-async
Its responsibility is to determine whether the README needs updating.
Do not edit README.md directly from symphony-orchestrator.
Possible results:
README_UNCHANGED
README_UPDATED
README_BLOCKED
README_FAILED
If README is updated, it may create new working-tree changes.
Those changes must be evaluated before the workflow ends.
The Cascade
The complete cascade is:
┌──────────────────┐
│ symphony-orchestrator │
└────────┬─────────┘
│
▼
Detect Changes
│
▼
tests-async
/ \
▼ ▼
tdd-async bdd-async
\ /
▼ ▼
TUnit
│
PASS / FAIL
│
PASS
▼
commit-async
│
User approval
│
▼
COMMIT
│
User approval
│
▼
PUSH
│
▼
auto-release
│
▼
CHANGELOG
+
TAG
│
▼
readme-async
│
▼
Detect Changes
Loop Behavior
The pipeline is allowed to repeat.
However, it must NEVER loop indefinitely.
The fundamental stopping condition is:
NO NEW RELEVANT CHANGES
Example:
Initial changes
↓
Tests
↓
Commit
↓
Push
↓
Release
↓
README update
↓
Check Git status
↓
No changes
↓
STOP
Change Cascade
If readme-async creates changes:
README update
↓
new changes detected
↓
tests-async
↓
commit-async
↓
push
↓
auto-release if required
↓
readme-async
↓
check changes again
Only continue when there are genuinely new relevant changes.
Loop Prevention
The orchestrator must detect repeated cycles.
Maintain an internal execution context containing:
- iteration number;
- initial HEAD;
- current HEAD;
- files changed;
- skills executed;
- commits created;
- release version;
- README modifications.
Set a reasonable maximum number of iterations.
Default:
MAX_ITERATIONS = 3
If the workflow reaches the maximum:
STOP.
Return:
SYMPHONY_LOOP_LIMIT_REACHED
Explain which files or skills caused the repeated cycle.
Never continue indefinitely.
Self-Generated Changes
The orchestrator must distinguish between:
USER_CHANGES
and:
AUTOMATION_CHANGES
Examples of automation changes:
- CHANGELOG.md;
- README.md;
- generated documentation;
- generated release metadata.
Automation-generated changes may trigger another iteration.
However, if the same automation repeatedly modifies the same file without stabilizing, stop.
Return:
SYMPHONY_UNSTABLE
No Change Termination
The workflow terminates successfully when:
git status --short
returns no relevant changes.
Return:
SYMPHONY_COMPLETED
Example:
SYMPHONY_COMPLETED
iterations: 2
tests: passed
commits: 2
releases: 1
readme_updates: 1
working_tree: clean
Release Loop Prevention
A release must not cause another release unless a new Conventional Commit requiring a release exists.
Do not create a release from:
- the same commit;
- the same tag;
- an unchanged repository.
A README-only change may produce a documentation commit.
Whether that documentation commit requires a release depends on the Conventional Commit type.
For example:
docs: update README
may produce no release depending on the project's release policy.
Conventional Commits
symphony-orchestrator does not generate commit messages itself.
Delegate this to:
commit-async
The commit skill owns Conventional Commit proposal and approval.
Human Approval
Human approval is mandatory for:
- commit creation;
- pushing commits;
- destructive or remote operations;
- release tag pushing when applicable.
Never simulate approval.
Never assume approval.
Never automatically answer approval prompts.
Error Handling
Any failure must stop the dependent part of the pipeline.
Examples:
TESTS_FAILED
→ STOP
COMMIT_FAILED
→ STOP
PUSH_FAILED
→ STOP
RELEASE_FAILED
→ STOP
README_FAILED
→ STOP or report according to the documentation contract
Never continue after a failed quality gate.
Skill Contracts
symphony-orchestrator must communicate with skills through explicit results.
Expected contracts:
tests-async:
TESTS_PASSED
TESTS_FAILED
TESTS_BLOCKED
TESTS_NOT_REQUIRED
commit-async:
COMMIT_CREATED
PUSH_COMPLETED
COMMIT_REJECTED
PUSH_REJECTED
COMMIT_FAILED
PUSH_FAILED
NO_CHANGES
auto-release:
NO_RELEASE
RELEASE_CREATED
RELEASE_BLOCKED
RELEASE_FAILED
CHANGELOG_UPDATED
TAG_CREATED
readme-async:
README_UNCHANGED
README_UPDATED
README_BLOCKED
README_FAILED
Skill Independence
Specialized skills must remain independent.
symphony-orchestrator must not:
- implement TDD;
- implement BDD;
- implement Conventional Commit generation;
- calculate semantic versions;
- directly modify README;
- directly modify CHANGELOG;
- directly create release tags.
Delegate those responsibilities.
Security
Never execute:
git reset --hard
git clean -fd
git push --force
Never delete user changes.
Never overwrite unrelated files.
Never automatically resolve conflicts by discarding changes.
Never commit unrelated files.
Never push without explicit approval.
Never create infinite loops.