synorch 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -1
- package/README.md +314 -28
- package/dist/application/doctor-service.d.ts +16 -0
- package/dist/application/doctor-service.d.ts.map +1 -1
- package/dist/application/doctor-service.js +230 -32
- package/dist/application/doctor-service.js.map +1 -1
- package/dist/application/generated-skill-doctor.d.ts +9 -0
- package/dist/application/generated-skill-doctor.d.ts.map +1 -0
- package/dist/application/generated-skill-doctor.js +433 -0
- package/dist/application/generated-skill-doctor.js.map +1 -0
- package/dist/application/project-discovery.d.ts +12 -0
- package/dist/application/project-discovery.d.ts.map +1 -1
- package/dist/application/project-discovery.js +65 -2
- package/dist/application/project-discovery.js.map +1 -1
- package/dist/application/safe-path.d.ts +19 -0
- package/dist/application/safe-path.d.ts.map +1 -0
- package/dist/application/safe-path.js +35 -0
- package/dist/application/safe-path.js.map +1 -0
- package/dist/application/size-ceiling.d.ts +15 -0
- package/dist/application/size-ceiling.d.ts.map +1 -0
- package/dist/application/size-ceiling.js +32 -0
- package/dist/application/size-ceiling.js.map +1 -0
- package/dist/application/structure-service.d.ts.map +1 -1
- package/dist/application/structure-service.js +10 -1
- package/dist/application/structure-service.js.map +1 -1
- package/dist/cli.js +10 -1
- package/dist/cli.js.map +1 -1
- package/dist/domain/canonical-contracts.d.ts +69 -0
- package/dist/domain/canonical-contracts.d.ts.map +1 -0
- package/dist/domain/canonical-contracts.js +92 -0
- package/dist/domain/canonical-contracts.js.map +1 -0
- package/dist/domain/generated-skill.d.ts +55 -0
- package/dist/domain/generated-skill.d.ts.map +1 -0
- package/dist/domain/generated-skill.js +90 -0
- package/dist/domain/generated-skill.js.map +1 -0
- package/dist/domain/generation.d.ts +15 -2
- package/dist/domain/generation.d.ts.map +1 -1
- package/dist/domain/observation-ledger.d.ts +118 -0
- package/dist/domain/observation-ledger.d.ts.map +1 -0
- package/dist/domain/observation-ledger.js +183 -0
- package/dist/domain/observation-ledger.js.map +1 -0
- package/dist/domain/product.d.ts +1 -1
- package/dist/domain/product.js +1 -1
- package/dist/domain/relative-path.d.ts +21 -0
- package/dist/domain/relative-path.d.ts.map +1 -0
- package/dist/domain/relative-path.js +43 -0
- package/dist/domain/relative-path.js.map +1 -0
- package/dist/domain/skill-packs.d.ts.map +1 -1
- package/dist/domain/skill-packs.js +1 -0
- package/dist/domain/skill-packs.js.map +1 -1
- package/dist/domain/zod-issues.d.ts +21 -0
- package/dist/domain/zod-issues.d.ts.map +1 -0
- package/dist/domain/zod-issues.js +27 -0
- package/dist/domain/zod-issues.js.map +1 -0
- package/dist/infrastructure/frontmatter.d.ts +25 -0
- package/dist/infrastructure/frontmatter.d.ts.map +1 -0
- package/dist/infrastructure/frontmatter.js +75 -0
- package/dist/infrastructure/frontmatter.js.map +1 -0
- package/dist/templates/agent-manifests.d.ts +19 -0
- package/dist/templates/agent-manifests.d.ts.map +1 -0
- package/dist/templates/agent-manifests.js +302 -0
- package/dist/templates/agent-manifests.js.map +1 -0
- package/dist/templates/base-skills.d.ts +23 -0
- package/dist/templates/base-skills.d.ts.map +1 -0
- package/dist/templates/base-skills.js +477 -0
- package/dist/templates/base-skills.js.map +1 -0
- package/dist/templates/skill-creator-skill.d.ts +23 -0
- package/dist/templates/skill-creator-skill.d.ts.map +1 -0
- package/dist/templates/skill-creator-skill.js +235 -0
- package/dist/templates/skill-creator-skill.js.map +1 -0
- package/dist/templates/skill-references.d.ts +13 -0
- package/dist/templates/skill-references.d.ts.map +1 -0
- package/dist/templates/skill-references.js +280 -0
- package/dist/templates/skill-references.js.map +1 -0
- package/dist/templates/structure-templates.d.ts.map +1 -1
- package/dist/templates/structure-templates.js +15 -139
- package/dist/templates/structure-templates.js.map +1 -1
- package/dist/templates/task-conductor-skill.d.ts +1 -1
- package/dist/templates/task-conductor-skill.d.ts.map +1 -1
- package/dist/templates/task-conductor-skill.js +50 -22
- package/dist/templates/task-conductor-skill.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.3.0] - 2026-09-22
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Canonical Agent Manifest v1 and Canonical Skill Contract v1: machine-checkable frontmatter for every generated agent and skill, validated by `doctor` alongside the required body sections and a numbered `Procedure`.
|
|
15
|
+
- Per-layer byte ceilings enforced by `doctor` — entrypoint 2 500, constitution 1 500, core protocol 2 000, agent manifest 3 000, base skill 6 000, reference file 15 000 — with depth moved into `references/` files that load only when a procedure step needs them.
|
|
16
|
+
- `skill-creator`, the ninth canonical base skill: it distills repeatedly confirmed project knowledge into a generated project skill after three confirmations from distinct tasks, or immediately on a user correction.
|
|
17
|
+
- A Git-tracked observation ledger at `.ai/tasks/observations.yaml`, seeded by `init`, plus a `.ai/tasks/.gitignore` that keeps per-task working records local.
|
|
18
|
+
- A generated-skill contract for `.ai/skills/project/**` enforced by `doctor`: evidence with existing in-root sources and matching digests, a `priority: skill` ceiling, a 15KB size limit, a twelve active-skill budget, confirming task ids that must exist in the ledger, and shape warnings for incident-log narration, missing triggers and unsourced claims.
|
|
19
|
+
- `sync` prunes expired observations and reports how many it removed.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- Retirement guidance now matches the implemented first slice: `doctor` detects stale evidence, while unused-skill and supersession decisions remain review-driven until usage telemetry exists.
|
|
24
|
+
- Agent manifests and base skills were rewritten to contract depth, with `not_for`, `inputs`, `tools`, `outputs`, `allowed_skills` and `reports` promoted from prose into frontmatter.
|
|
25
|
+
- `sync` never creates, overwrites or deletes anything under `.ai/skills/project/**`, with or without `--force`.
|
|
26
|
+
- Existing 0.2.x structures must be regenerated with `syn init --force` followed by `syn sync --force` to pick up the canonical contracts, the ninth base skill and the observation ledger.
|
|
27
|
+
- Hand-written agent directories under `.ai/agents/` are now held to the Canonical Agent Manifest contract: `doctor` reports a missing `AGENT.md`, invalid frontmatter, a name that does not match its directory, an unknown skill reference or a missing required section as an error.
|
|
28
|
+
- `init` never overwrites `.ai/tasks/observations.yaml`. The ledger is seeded when absent and preserved from then on, with or without `--force`, and `inspect` and `init` report it as `preserved` rather than `update` or `conflict`. `.ai/tasks/.gitignore` remains canonical and is still refreshed by `--force`.
|
|
29
|
+
- Activating a generated project skill is expressed by `status: active` in the skill's own frontmatter and by the observation moving to `status: promoted` with the new optional `promoted_to` link. There is no registry entry: `.ai/projects/<id>.skills.yaml` has no project-skill slot and is regenerated by every `sync`.
|
|
30
|
+
- Agent manifests no longer restate the procedure, required inputs, stop conditions or output contract of their primary skills; each points at the skill that owns them, so a rule lives in exactly one layer.
|
|
31
|
+
- `sync` fails explicitly with exit code 2 on a schema-invalid observation ledger instead of pruning or rewriting it.
|
|
32
|
+
- `doctor` reports `generated.broken-promotion-link` when a `promoted` observation's `promoted_to` names no skill under `.ai/skills/project/`.
|
|
33
|
+
- Recorded digest prefixes must now be at least 32 hex characters, in both the observation ledger and generated-skill evidence; a shorter prefix no longer counts as a digest match.
|
|
34
|
+
- Diagnostics that reported a schema failure now render it as `path: message` on one line instead of a raw zod JSON dump, and a defect that has a dedicated code is no longer also reported as a generic contract violation.
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
|
|
38
|
+
- A generated skill could declare a `references` entry with a UNC root, a drive letter or a `..` segment and receive no diagnostic, and declared references were never resolved at all. The lexical rule is now shared with the canonical checks and applied before the absolute-path test, and `diagnoseGeneratedSkills` validates containment, existence and the 15000-byte ceiling under `generated.unsafe-reference-path`, `generated.missing-reference-file` and `generated.reference-size` (a warning, like every other layer ceiling).
|
|
39
|
+
|
|
10
40
|
## [0.2.0] - 2026-09-21
|
|
11
41
|
### Added
|
|
12
42
|
|
|
@@ -36,6 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
36
66
|
- A bundled, provenance-tracked Ingenium skill catalog with on-demand loading rules.
|
|
37
67
|
- Model profiles, orchestration protocols, minimal context packets, verification contracts, and provider adapters.
|
|
38
68
|
|
|
39
|
-
[Unreleased]: https://github.com/TunahanTuna/synorch/compare/v0.
|
|
69
|
+
[Unreleased]: https://github.com/TunahanTuna/synorch/compare/v0.3.0...HEAD
|
|
70
|
+
[0.3.0]: https://github.com/TunahanTuna/synorch/compare/v0.2.0...v0.3.0
|
|
40
71
|
[0.2.0]: https://github.com/TunahanTuna/synorch/compare/v0.1.0...v0.2.0
|
|
41
72
|
[0.1.0]: https://github.com/TunahanTuna/synorch/releases/tag/v0.1.0
|
package/README.md
CHANGED
|
@@ -1,60 +1,346 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# Synorch
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
**Turn any repository into an orchestrator-led AI development organization — in one command.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/synorch)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
|
|
11
|
+
`npx synorch init` · works with **Codex** and **Claude Code** · zero runtime, zero lock-in
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Why Synorch exists
|
|
18
|
+
|
|
19
|
+
Coding agents are already good at writing code. What they are bad at is *running a project*.
|
|
20
|
+
|
|
21
|
+
Left alone, a single agent session drifts in predictable ways. It starts implementing before anyone agreed on a plan. It re-reads the same repository from scratch in every subagent, burning tokens on facts it already knew. It grades its own homework, so the review is never independent. It guesses your stack instead of proving it. And every new session starts from zero, because nothing it learned was written down anywhere durable.
|
|
22
|
+
|
|
23
|
+
Synorch fixes the *organization* around the model, not the model itself.
|
|
24
|
+
|
|
25
|
+
It is a CLI that installs a provider-neutral **orchestration system** into a folder, a repository, or a multi-repo workspace: one decision-making orchestrator, a set of specialized worker roles, constitutional protocols they cannot override, evidence-backed project facts, and a skill library that loads only when it is actually needed. After `syn init` and `syn sync`, you keep working exactly as before — inside Codex or Claude Code — except the agent now operates inside a structure with rules, memory, and receipts.
|
|
26
|
+
|
|
27
|
+
### What it is not
|
|
28
|
+
|
|
29
|
+
Synorch is deliberately small in scope, and honest about it:
|
|
4
30
|
|
|
5
|
-
|
|
31
|
+
- It is **not** a model runtime. It never calls an API, never holds your keys, never runs a conversation loop.
|
|
32
|
+
- It is **not** a background daemon. Nothing watches your files. Every action is a command you type.
|
|
33
|
+
- It is **not** another coding assistant. It makes the one you already pay for behave like a team.
|
|
34
|
+
- It **never invents** your architecture. Empty folder in, generic core out — no hallucinated project facts.
|
|
35
|
+
- It **never fakes** provider capabilities. If Codex or Claude Code can't do something, `syn doctor` tells you instead of pretending a markdown file solved it.
|
|
6
36
|
|
|
7
|
-
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# Inside an existing repository — no install needed
|
|
43
|
+
npx synorch init # install the orchestration core
|
|
44
|
+
npx synorch sync # discover the real stack from evidence
|
|
45
|
+
npx synorch doctor # verify every reference end to end
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Prefer a global install and the short command:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm install --global synorch
|
|
52
|
+
syn init && syn sync && syn doctor
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Other package managers work the same way:
|
|
8
56
|
|
|
9
57
|
```bash
|
|
10
|
-
npx synorch init
|
|
11
58
|
pnpm dlx synorch init
|
|
12
59
|
yarn dlx synorch init
|
|
13
60
|
```
|
|
14
61
|
|
|
15
|
-
|
|
62
|
+
Then just open Codex or Claude Code in that folder. The generated `AGENTS.md` and `CLAUDE.md` become the entry point, and the orchestrator takes it from there.
|
|
63
|
+
|
|
64
|
+
> **Requires Node.js 24+.** Synorch ships as strict-TypeScript ESM and relies on Node's built-in type stripping — no transpiler in your dependency tree.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## The 60-second tour
|
|
16
69
|
|
|
17
70
|
```bash
|
|
18
|
-
|
|
19
|
-
|
|
71
|
+
$ syn inspect # dry run: exactly what would be written, and what would conflict
|
|
72
|
+
Target: /home/dev/acme-api
|
|
73
|
+
Scope: repository
|
|
74
|
+
+ create AGENTS.md
|
|
75
|
+
+ create CLAUDE.md
|
|
76
|
+
+ create .ai/constitution.md
|
|
77
|
+
+ create .ai/protocols/core/orchestration.md
|
|
78
|
+
...
|
|
79
|
+
! conflict .ai/skills/planning/SKILL.md
|
|
80
|
+
|
|
81
|
+
1 conflict(s) found. Existing files will not be overwritten without --force.
|
|
20
82
|
```
|
|
21
83
|
|
|
22
|
-
|
|
84
|
+
```bash
|
|
85
|
+
$ syn sync # evidence-driven discovery, then registry refresh
|
|
86
|
+
Discovered 3 project(s).
|
|
87
|
+
acme-api: services/api
|
|
88
|
+
acme-web: apps/web
|
|
89
|
+
acme-jobs: services/jobs
|
|
90
|
+
```
|
|
23
91
|
|
|
24
92
|
```bash
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
93
|
+
$ syn doctor # integrity check from workspace entry down to skill file
|
|
94
|
+
ERROR skill.registry.missing_file: Registered skill has no file on disk (.ai/skills/technology/react-patterns/SKILL.md)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`doctor` exits non-zero on any error, so it drops straight into CI.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## How the system works
|
|
102
|
+
|
|
103
|
+
### One decision center
|
|
104
|
+
|
|
105
|
+
You talk to the orchestrator. Only the orchestrator talks back to you. Everything else happens below the waterline.
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
You
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
┌─────────────┐
|
|
112
|
+
│ Orchestrator│ plans · decides · delegates · verifies
|
|
113
|
+
└──────┬──────┘
|
|
114
|
+
┌───────────┬───┴───────┬────────────┐
|
|
115
|
+
▼ ▼ ▼ ▼
|
|
116
|
+
Explorer Implementer Debugger Reviewer
|
|
117
|
+
(read-only) (scoped (root (independent
|
|
118
|
+
writes) cause) of the author)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The orchestrator is a control plane, not a contributor. It is forbidden from writing production, test, config, or documentation code — even when the change is one line. It may only write orchestration artifacts under `.ai/tasks/**`. The agent that implemented something can never be the final judge of it.
|
|
122
|
+
|
|
123
|
+
### Every task gets planned, approved, and proven
|
|
124
|
+
|
|
125
|
+
```text
|
|
126
|
+
SESSION_BOOTSTRAP → MODEL_PROFILE_CONFIRMATION → INTAKE → DISCOVERY
|
|
127
|
+
→ CLARIFICATION → PLAN → USER_APPROVAL → DECOMPOSITION → DISPATCH
|
|
128
|
+
→ MONITORING → VERIFICATION → REVIEW → FINAL_REPORT
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Two gates are non-negotiable. Before the first task of a session, the orchestrator shows you the active provider and the model assigned to every role and waits for confirmation. Before any execution, it shows you a plan and waits for approval. Nothing starts silently.
|
|
132
|
+
|
|
133
|
+
### Effort scales with risk
|
|
134
|
+
|
|
135
|
+
Full ceremony on a typo fix is just expensive theater. Synorch classifies every task before execution:
|
|
136
|
+
|
|
137
|
+
| Tier | Workers | Verification | Independent review |
|
|
138
|
+
| --- | --- | --- | --- |
|
|
139
|
+
| **trivial** | one fast worker | claim-specific evidence only | not by default |
|
|
140
|
+
| **standard** | matched to scope | targeted checks | on material or boundary-crossing changes |
|
|
141
|
+
| **high-risk** | complex worker | comprehensive evidence | mandatory |
|
|
142
|
+
|
|
143
|
+
Tiers can only be escalated — if a finding widens the scope mid-flight, the task moves up, never down. Headed-browser verification is opt-in: it needs either your explicit request or a named criterion that cheaper evidence genuinely cannot settle.
|
|
144
|
+
|
|
145
|
+
### Context packets instead of re-reading the repo
|
|
146
|
+
|
|
147
|
+
The expensive failure mode of multi-agent setups is that every worker rediscovers the same codebase. Synorch's answer is a schema'd handoff: the orchestrator does broad discovery **once**, then compiles a minimal, sourced packet per task.
|
|
148
|
+
|
|
149
|
+
```yaml
|
|
150
|
+
task_id: auth-refresh-fix-implementation
|
|
151
|
+
assigned_role: implementer
|
|
152
|
+
model_tier: complex_worker
|
|
153
|
+
|
|
154
|
+
objective: Fix the session loss that occurs during refresh token rotation.
|
|
155
|
+
|
|
156
|
+
scope:
|
|
157
|
+
owned_paths: [src/auth/**, tests/auth/**]
|
|
158
|
+
read_paths: [src/session/**]
|
|
159
|
+
forbidden_paths: [src/billing/**]
|
|
160
|
+
|
|
161
|
+
known_facts:
|
|
162
|
+
- statement: Token rotation is active on refresh
|
|
163
|
+
source: src/auth/refresh-service.ts
|
|
164
|
+
confidence: verified
|
|
165
|
+
|
|
166
|
+
acceptance_criteria:
|
|
167
|
+
- Replaying an old refresh token revokes the whole token family
|
|
168
|
+
- A normal refresh does not terminate the active session
|
|
169
|
+
|
|
170
|
+
verification:
|
|
171
|
+
commands: [pnpm test auth, pnpm typecheck]
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Workers report back in the same structured shape — changed files, commands run, decisions made, unresolved risks. Follow-up work uses **delta handoff** (`extends:` plus only what changed) rather than resending the whole packet. If a worker notices that the files its context was built on have shifted, it stops and escalates instead of acting on stale truth.
|
|
175
|
+
|
|
176
|
+
### Facts, not guesses
|
|
177
|
+
|
|
178
|
+
`syn sync` walks your repository or workspace deterministically and records what it can *prove*, with a source path attached to every claim:
|
|
179
|
+
|
|
180
|
+
```yaml
|
|
181
|
+
test:
|
|
182
|
+
value: pnpm test
|
|
183
|
+
cwd: frontend
|
|
184
|
+
source: package.json
|
|
185
|
+
confidence: verified
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
It parses JavaScript/TypeScript manifests plus Maven and Gradle definitions, and it is careful about false positives: commented-out coordinates and entries sitting only under dependency/plugin *management* do not count as evidence of an active framework. Nested module trees are discovered recursively, with a separate depth budget so a deep Java source tree isn't silently truncated. When a safety limit is genuinely reached, sync fails loudly rather than handing you an incomplete snapshot.
|
|
189
|
+
|
|
190
|
+
### Skills load just in time
|
|
191
|
+
|
|
192
|
+
Every project registry gets the same nine canonical base skills:
|
|
193
|
+
|
|
194
|
+
`planning` · `project-discovery` · `codebase-exploration` · `implementation` · `verification` · `debugging` · `code-review` · `task-conductor` · `skill-creator`
|
|
195
|
+
|
|
196
|
+
Technology skills are added **only** when matching verified evidence exists:
|
|
197
|
+
|
|
198
|
+
| Detected | Activated skills |
|
|
199
|
+
| --- | --- |
|
|
200
|
+
| TypeScript | `typescript-patterns` |
|
|
201
|
+
| React | `react-patterns`, `react-modern`, `frontend-craft` |
|
|
202
|
+
| Vue / Nuxt | `vue-modern`, `frontend-craft` |
|
|
203
|
+
| Java | `java-patterns`, `java-backend` |
|
|
204
|
+
| Spring Boot | `spring-boot-patterns` |
|
|
205
|
+
| JPA / Hibernate | `jpa-patterns`, `db-schema-craft`, `query-tuning` |
|
|
206
|
+
| Express / Fastify / NestJS | `node-backend` |
|
|
207
|
+
| Maven · Gradle | `maven-build` · `gradle-build` |
|
|
208
|
+
| Tailwind CSS | `tailwind-v4-tokens` |
|
|
209
|
+
|
|
210
|
+
Beyond that, `sync` materializes a bundled 32-skill Ingenium library under `.ai/skills/library/ingenium/`, with source, license, and provenance recorded in `.ai/skills/catalog.yaml`. Those entries stay `available`, not loaded — the orchestrator pulls one into context only when a task description actually matches its description. Loading the whole pool at once is explicitly forbidden, which is the difference between a useful library and a context bill.
|
|
211
|
+
|
|
212
|
+
Three states, kept distinct: **available** (in the catalog) → **active** (in a project registry) → **loaded** (in a task context). Session bootstrap never scans the catalog.
|
|
213
|
+
|
|
214
|
+
Anthropic Agent Skills, Superpowers, and Microsoft Agent Skills are catalogued `reference-only` with pinned commit IDs. Third-party content is never auto-imported or executed without a separate security and license review.
|
|
215
|
+
|
|
216
|
+
### Provider-neutral core, honest adapters
|
|
217
|
+
|
|
218
|
+
Protocols are written against capability tiers, not vendor model names:
|
|
219
|
+
|
|
220
|
+
```yaml
|
|
221
|
+
model_tiers:
|
|
222
|
+
orchestrator: [strongest_reasoning, delegation, long_context]
|
|
223
|
+
complex_worker: [strong_coding, autonomous_execution]
|
|
224
|
+
fast_worker: [low_latency, low_cost]
|
|
28
225
|
```
|
|
29
226
|
|
|
30
|
-
|
|
227
|
+
Adapters map those tiers onto the real model IDs of whichever provider you're running, with overrides resolving session → project → workspace → provider default. **Silent fallback is banned.** If a requested model isn't available, or the provider doesn't support per-subagent model selection, or the main session model can't be changed mid-flight, you are told — by `doctor` and again at session confirmation. Synorch will never let a markdown file imply a capability the host doesn't actually have.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Commands
|
|
31
232
|
|
|
32
233
|
```bash
|
|
33
234
|
syn inspect [--target <path>] [--scope workspace|repository]
|
|
34
|
-
syn init
|
|
35
|
-
syn sync
|
|
36
|
-
syn doctor
|
|
235
|
+
syn init [--target <path>] [--scope workspace|repository] [--force]
|
|
236
|
+
syn sync [--target <path>] [--force] [--json]
|
|
237
|
+
syn doctor [--target <path>] [--json]
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
| Command | What it does |
|
|
241
|
+
| --- | --- |
|
|
242
|
+
| `inspect` | Dry run. Prints every file that would be created, updated, left unchanged, or flagged as a conflict. Writes nothing. |
|
|
243
|
+
| `init` | Installs the canonical structure and provider entrypoints. Never touches your source code. Existing differing files are preserved unless `--force`. |
|
|
244
|
+
| `sync` | Manually triggered discovery. Records project facts with evidence, resolves skills, writes registries. Refuses to clobber hand-edited generated files without `--force`. |
|
|
245
|
+
| `doctor` | Validates the full reference chain — workspace entry → project record → module dirs → manifests → command `cwd` → skill registry → skill file — plus canonical base-skill completeness and path containment (both lexical traversal and `realpath` symlink/junction escapes). |
|
|
246
|
+
|
|
247
|
+
`--json` on `sync` and `doctor` gives machine-readable output for CI pipelines.
|
|
248
|
+
|
|
249
|
+
**Safety defaults that actually hold:** existing differing files are never overwritten without an explicit `--force`, and the observation ledger `.ai/tasks/observations.yaml` is never overwritten even with it — it is seeded once and reported as `preserved` thereafter; the active skill registry is written *last*, after every prerequisite output, so a failed write leaves the previous working registry intact; and nothing is reported `healthy` while a single reference is missing, broken, duplicated, or pointing outside the root.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Generated structure
|
|
254
|
+
|
|
255
|
+
```text
|
|
256
|
+
.ai/
|
|
257
|
+
├── manifest.yaml
|
|
258
|
+
├── constitution.md # constitutional, non-overridable rules
|
|
259
|
+
├── workspace.yaml
|
|
260
|
+
├── projects/
|
|
261
|
+
│ ├── <project-id>.yaml # evidence-backed project facts
|
|
262
|
+
│ └── <project-id>.skills.yaml # skill selections + rationale + matched evidence
|
|
263
|
+
├── protocols/
|
|
264
|
+
│ ├── registry.yaml
|
|
265
|
+
│ └── core/
|
|
266
|
+
│ ├── orchestration.md planning-and-approval.md
|
|
267
|
+
│ ├── delegation.md model-routing.md
|
|
268
|
+
│ ├── context-handoff.md verification.md
|
|
269
|
+
│ ├── failure-recovery.md user-communication.md
|
|
270
|
+
├── agents/
|
|
271
|
+
│ └── <role>/AGENT.md # Canonical Agent Manifest v1, one per role:
|
|
272
|
+
│ # orchestrator · explorer · implementer · reviewer · debugger
|
|
273
|
+
├── skills/
|
|
274
|
+
│ ├── <canonical base skills>/SKILL.md # Canonical Skill Contract v1
|
|
275
|
+
│ │ └── references/*.md # depth loaded only when a step needs it
|
|
276
|
+
│ ├── technology/<selected>/SKILL.md
|
|
277
|
+
│ ├── project/<generated>/SKILL.md # earned project skills; sync never writes here
|
|
278
|
+
│ ├── library/ingenium/** # bundled, on-demand
|
|
279
|
+
│ └── catalog.yaml # provenance, license, activation mode
|
|
280
|
+
├── model-profiles/
|
|
281
|
+
│ ├── openai.yaml
|
|
282
|
+
│ └── claude.yaml
|
|
283
|
+
├── tasks/ # plans, context packets, decision log
|
|
284
|
+
│ ├── observations.yaml # the Git-tracked observation ledger
|
|
285
|
+
│ └── .gitignore # per-task working records stay local
|
|
286
|
+
└── providers/
|
|
287
|
+
├── codex.md
|
|
288
|
+
└── claude-code.md
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Plus `AGENTS.md` and `CLAUDE.md` at the root as provider entrypoints.
|
|
292
|
+
|
|
293
|
+
### Workspace mode vs. repository mode
|
|
294
|
+
|
|
295
|
+
**Repository mode** puts the structure inside a single repo, so it travels through Git and the whole team shares it.
|
|
296
|
+
|
|
297
|
+
**Workspace mode** puts one shared system in a parent folder above several repositories, each tracked as its own project record:
|
|
298
|
+
|
|
299
|
+
```text
|
|
300
|
+
workspace/
|
|
301
|
+
├── AGENTS.md
|
|
302
|
+
├── CLAUDE.md
|
|
303
|
+
├── .ai/
|
|
304
|
+
├── repo-a/
|
|
305
|
+
└── repo-b/
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Cloned a new repo into the workspace? Run `syn sync`. There is no watcher and no full re-`init`.
|
|
309
|
+
|
|
310
|
+
On an empty folder, Synorch installs the generic orchestration core and stops. No invented stack, no imaginary architecture, `projects: []`.
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## Contributing
|
|
315
|
+
|
|
316
|
+
```bash
|
|
317
|
+
pnpm install
|
|
318
|
+
pnpm check # typecheck + test + build
|
|
319
|
+
pnpm dev -- inspect # run the CLI from source
|
|
37
320
|
```
|
|
38
321
|
|
|
39
|
-
|
|
322
|
+
`pnpm check` also runs as a `prepack` gate, so nothing ships without passing typecheck, tests, and build. Package contents are restricted by an explicit allowlist, CI uses read-only default permissions with pinned action SHAs, and npm releases go out through Trusted Publishing (OIDC) — no long-lived tokens stored anywhere.
|
|
40
323
|
|
|
41
|
-
|
|
324
|
+
---
|
|
42
325
|
|
|
43
|
-
|
|
326
|
+
## Documentation
|
|
44
327
|
|
|
45
|
-
|
|
328
|
+
| Document | Contents |
|
|
329
|
+
| --- | --- |
|
|
330
|
+
| [Architecture](./docs/AI-ORCHESTRATION-ARCHITECTURE.md) | The full design: orchestration model, protocol system, context architecture, model routing, discovery, open decisions, and the dated decision log. |
|
|
331
|
+
| [Multi-provider harness vision](./docs/FUTURE-MULTI-PROVIDER-HARNESS.md) | Where this goes next — running different providers in different roles under one orchestrator. Proposal stage, not implemented. |
|
|
332
|
+
| [CHANGELOG](./CHANGELOG.md) | Version history, Keep a Changelog + SemVer. |
|
|
333
|
+
| [Release notes v0.3.0](./docs/releases/v0.3.0.md) | Human-readable notes for the current release. |
|
|
334
|
+
| [Security policy](./SECURITY.md) | Report vulnerabilities through the private channel, not a public issue. |
|
|
46
335
|
|
|
47
|
-
|
|
336
|
+
---
|
|
48
337
|
|
|
49
|
-
|
|
338
|
+
## Roadmap
|
|
50
339
|
|
|
51
|
-
|
|
340
|
+
Today Synorch generates and validates the structure; your host agent executes it. The [multi-provider harness proposal](./docs/FUTURE-MULTI-PROVIDER-HARNESS.md) sketches a future layer that could connect authorized provider accounts, run different models in different roles under one orchestrator, persist task state, and manage the implementation-to-review flow across vendors. That layer is not implemented, and this README will not pretend otherwise.
|
|
52
341
|
|
|
53
|
-
|
|
342
|
+
---
|
|
54
343
|
|
|
55
|
-
|
|
56
|
-
- Sürüm geçmişi için [CHANGELOG.md](./CHANGELOG.md) dosyasını inceleyin.
|
|
57
|
-
- Güvenlik açıklarını herkese açık issue yerine [güvenlik politikasındaki](./SECURITY.md) özel bildirim akışıyla paylaşın.
|
|
58
|
-
- Synorch, [MIT lisansı](./LICENSE) altında yayımlanır.
|
|
344
|
+
## License
|
|
59
345
|
|
|
60
|
-
|
|
346
|
+
MIT © [Tunahan Tuna](https://github.com/TunahanTuna) — see [LICENSE](./LICENSE).
|
|
@@ -16,6 +16,22 @@ export declare class DoctorService {
|
|
|
16
16
|
private validateCommandPaths;
|
|
17
17
|
private validateSkillRegistry;
|
|
18
18
|
private validateRegisteredSkills;
|
|
19
|
+
/**
|
|
20
|
+
* Canonical Agent Manifest v1 and Canonical Skill Contract v1 enforcement.
|
|
21
|
+
* Contract violations are errors; layer size overruns are warnings.
|
|
22
|
+
*/
|
|
23
|
+
private validateCanonicalContracts;
|
|
24
|
+
private validateAgentManifest;
|
|
25
|
+
private validateSkillContract;
|
|
26
|
+
/**
|
|
27
|
+
* A declared reference must resolve inside its own skill directory both
|
|
28
|
+
* lexically and after symbolic links are canonicalized.
|
|
29
|
+
*/
|
|
30
|
+
private validateSkillReferences;
|
|
31
|
+
private checkFileSize;
|
|
32
|
+
private readOptionalText;
|
|
33
|
+
private listDirectoryNames;
|
|
34
|
+
private listMarkdownFiles;
|
|
19
35
|
private isExistingDirectory;
|
|
20
36
|
private isExistingRegularFile;
|
|
21
37
|
private isCanonicalPathWithin;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"doctor-service.d.ts","sourceRoot":"","sources":["../../src/application/doctor-service.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"doctor-service.d.ts","sourceRoot":"","sources":["../../src/application/doctor-service.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAgBnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAoBD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAErB,UAAU,EAAE,UAAU;IAI5B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;YA4FhE,sBAAsB;YAkItB,0BAA0B;YA+F1B,2BAA2B;YA+B3B,oBAAoB;YAqDpB,qBAAqB;YA4DrB,wBAAwB;IAiHtC;;;OAGG;YACW,0BAA0B;YAmB1B,qBAAqB;YA0DrB,qBAAqB;IAgDnC;;;OAGG;YACW,uBAAuB;YAgDvB,aAAa;YAWb,gBAAgB;YAShB,kBAAkB;YAalB,iBAAiB;YAajB,mBAAmB;YAOnB,qBAAqB;YAOrB,qBAAqB;YASrB,gBAAgB;CAgD/B"}
|