convez.ai
SkillAutomaçãoAvançado
Syntran-Labs

Syntran AIEOS – Sistema Operacional de Engenharia IA

Syntran-Labs/syntran-aieos

Governança e workflows repetíveis para Claude Code com rastreamento completo

Ver no GitHub
BomPluginScore · de 0 a 100

Um sistema operacional para Claude Code que implementa governança, workflows repetíveis, portões de permissão explícitos e telemetria autossupervisora. Mapeia conceitos de SO (kernel, processos, skills, domínios) sobre Claude Code, garantindo consistência comportamental, rastreabilidade e controle de segurança desde o primeiro dia. Otimizado para Windows.

Instalação

$npx convez-ai Syntran-Labs/syntran-aieos

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 5 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Líderes técnicos usando Claude Code em múltiplos projetos com governança central
  • Engenheiros IA construindo pipelines de automação auditáveis e repetíveis
  • Equipes que precisam de permissões explícitas e rastreamento de todas as ações de IA

Veredito

Syntran é um framework sério e bem arquitetado para quem quer elevar Claude Code de ferramenta ad-hoc para sistema produção-ready com governança rigorosa. Excelente para orquestradores de workflow e engenheiros que precisam de auditoria.

README

A tradução para o português deste README ainda está na fila.

SyntranAI AIEOS

An AI Engineering Operating System — not a prompt collection.

SYNTRAN turns Claude Code into a governed implementation partner: consistent roles, repeatable workflows, explicit permission boundaries, and a self-measuring telemetry layer. Every session starts from the same behavioral baseline. Every action is traceable. Every sensitive change requires approval.


The Problem With Raw Claude Code

An unconfigured Claude Code session is powerful but stateless from a behavioral standpoint:

  • No consistent definition of what Claude should and should not do
  • No repeatable workflows — quality depends on how well you phrase each prompt
  • No permission model — nothing stops Claude from silently modifying production configs
  • No traceability — you can't measure whether structured prompting actually helps
  • Every project starts from scratch

SYNTRAN solves all four.


Who Is This For?

  • Solo technical leads and senior engineers who use Claude Code across multiple projects
  • AI engineers who want repeatable, traceable workflows instead of ad-hoc prompting
  • Anyone building production systems with Claude Code who wants governance from day one
  • Teams who need to explain and audit what their AI assistant was asked to do

Architecture

SYNTRAN maps directly onto OS concepts. Claude Code is the runtime. SYNTRAN is what runs on it.

OS ConceptSYNTRAN EquivalentLocation
Kernel (governance layer)Governance model — defines and enforces all safety rules through behavioral instructionCLAUDE.md + governance/
ProcessesAgents — specialist execution contexts with defined output contractsagents/
System callsSkills — standardized operation contracts with explicit workflowsskills/
Device driversDomains — area-specific knowledge packs (facts, config, constraints)domains/
ApplicationsProjects — tenant workloads that inherit all OS-level rulesprojects/
Boot sequenceCLAUDE.md auto-loads at every session startAlways
Process monitorTelemetry — hooks that log every prompt, command, and token counttelemetry/
Execution engineClaude CodeRuntime (not the OS itself)

Quick Start

The framework itself requires no installation — it is Markdown files, nothing to package or deploy. Runtime dependencies are listed below.

Runtime dependencies:

  • VSCode with the Claude Code extension
  • PowerShell 5.1 (telemetry hooks — Windows built-in)
  • Ollama (optional, for local inference)
1. Clone or download this repo and open syntran-aieos/ in VSCode with the Claude Code extension.
2. CLAUDE.md loads automatically — governance is active from the first message.
3. Type /synw- in the chat input to browse available agents and skills.

First invocation:

Use python-engineer.
Apply develop.
Relevant domains: local-inference
Task: Write a script that calls Ollama to summarize a text file.
Constraints: llama3.2:3b, no external dependencies beyond requests, Python 3.11+

Claude will restate the objective, declare assumptions, design the approach, implement, and produce a completion summary — in that order, every time.


Governance

Governance is the kernel. It is always active and never needs to be invoked. Every action is classified before execution:

CategoryExamplesGate
SafeReading, analyzing, proposing, drafting, documentingProceed
ModerateCreating files, scaffolding, config templates, adding testsDeclare plan → proceed
SensitiveModifying existing code, schemas, pipelines, auth flowsExplicit approval required
CriticalCredentials, production configs, IAM, DB operations, deploymentsExplicit approval required
ForbiddenDeploy to prod, rotate secrets, delete prod data, disable securityNever

When a Sensitive or Critical action is required, Claude stops and issues a structured approval request:

Approval Required

Intent:     [what Claude intends to do]
Files:      [list of files impacted]
Reason:     [why this is necessary]
Risks:      [what could go wrong]
Rollback:   [how to undo]

Proceed?

Claude is instructed to halt at this gate pending explicit approval. This is behavioral contract, not hard enforcement — the governance model works through instruction, not sandboxing. See SECURITY.md for the full scope and limits of this model.


Agents

Agents define who handles the task — role, focus, output contract, and escalation boundaries.

AgentBest ForSlash Command
ArchitectSolution design, tradeoff analysis, system decomposition/synw-agent-architect
Python EngineerImplementation, refactoring, testing, pipelines/synw-agent-python-engineer
Security ReviewerRisk identification, vulnerability surfacing, auth review/synw-agent-security-reviewer
Technical WriterGuides, references, explanations, ADRs, READMEs/synw-agent-technical-writer
Test Strategy LeadRisk-based test planning, release quality gates/synw-agent-test-strategy-lead
Test Automation EngineerAutomated test design, fixtures, component/integration/E2E/synw-agent-test-automation-engineer
Release Test ManagerRelease validation coordination, go/no-go recommendations/synw-agent-release-test-manager

Definitions: agents/


Skills

Skills define how the task is executed — the exact workflow, validation expectations, and when to stop and escalate.

SkillBest ForSlash Command
DevelopNew features, modules, scripts, integrations/synw-skill-develop
RefactorRestructuring existing code without behavior change/synw-skill-refactor
DebugSystematic root-cause diagnosis and fix/synw-skill-debug
ReviewCode, architecture, and documentation review/synw-skill-review
DocumentTyped documentation production (Tutorial / How-to / Reference / Explanation)/synw-skill-document
Test PlanTest strategy, risk mapping, coverage model, release gates/synw-skill-test-plan
E2E RegressionEnd-to-end regression test design/synw-skill-e2e-regression-testing
Release ValidationRelease readiness evidence and approval checklist/synw-skill-release-validation

Definitions: skills/


Testing Team

Nine specialist testing agents, ten testing skills, five domain packs, six templates, and two governance documents for quality-gated delivery.

RoleBest ForSlash Command
Test Strategy LeadTest planning, risk mapping, quality gates/synw-agent-test-strategy-lead
Test Automation EngineerUnit / component / integration / E2E test design and code/synw-agent-test-automation-engineer
QA Functional AnalystFunctional verification, acceptance criteria(direct invocation)
API Contract TesterAPI contract and schema validation(direct invocation)
Security Test ReviewerSecurity-focused test design(direct invocation)
Performance & Reliability TesterLoad, latency, failure mode tests(direct invocation)
Data Quality TesterData pipeline and AI output validation(direct invocation)
Accessibility & UX TesterWCAG, usability, interaction coverage(direct invocation)
Release Test ManagerRelease validation coordination, go/no-go recommendations/synw-agent-release-test-manager
Testing AssessmentFull project testing maturity and risk assessment/synw-test-assessment

All testing agents operate under the existing Safe / Moderate / Sensitive / Critical / Forbidden model. No additional permissions are granted. Creating test files is Moderate. Modifying production code, auth, schemas, or CI/CD is Sensitive or Critical.

Governance: governance/testing-approval-boundaries.md · governance/testing-risk-matrix.md Templates: templates/testing/


Domains

Domains are knowledge packs — area-specific facts, constraints, and configuration. Always declare domains explicitly in invocations for deterministic behavior; relying on inference introduces unpredictability.

DomainContents
local-inferenceOllama endpoint, hardware guidance, model inventory, routing rules
documentationDiátaxis document type taxonomy, project style guide
testing-frameworkCore testing concepts, level taxonomy, coverage model
frontend-react-testingReact component and UI testing patterns
backend-api-testingAPI contract, integration, and negative test patterns
data-ai-testingRAG/AI output validation, data quality checks
release-governanceRelease decision rules, go/no-go criteria

Projects

Projects are OS tenants. Each inherits the full governance model and adds its own stack, constraints, and agent/skill recommendations.

ProjectPurpose
WinFolderShiftRelocate Windows shell folders (Downloads, Documents) from C to a secondary drive via registry redirection
syntran-vscodeVSCode extension — agent/skill browser, invocation builder, live telemetry dashboard for Claude Code

To add a new project: create a profile.md under projects/<name>/ following the pattern in examples/projects/_template/.

Example profiles are available in examples/projects/.


Inference Routing

SYNTRAN runs two inference backends. The routing decision is a data sensitivity and task complexity call — not a cost optimization.

BackendEndpointModelUse When
Local (Ollama)http://localhost:11434llama3.2:3bPatient data, credentials, confidential context, or offline
Cloud (Claude)Anthropic APIclaude-sonnet-4-6Architecture, security, multi-file reasoning, final output

Important: llama3.2:3b is for low-risk work — summarization, classification, formatting, and private-context triage. It is not the final authority for architecture decisions, security reviews, or complex multi-file reasoning. Those always route to cloud.

Full routing rules: domains/local-inference/routing-guide.md


Telemetry

SYNTRAN measures itself. Three Claude Code hooks fire automatically — no manual instrumentation needed.

HookFires WhenLogs
UserPromptSubmitEvery user messageSession ID, timestamp, project
PostToolUse (Skill)Any agent or skill is invokedSession ID, command name
StopClaude finishes respondingInput tokens, output tokens, framework token estimate

CSV schema: telemetry/usage.csv

session_id, timestamp, user, project, event_type, command, input_tokens, output_tokens, framework_tokens

KPIs:

Command adoption rate     = sessions with ≥1 COMMAND row / total PROMPT sessions
Framework overhead ratio  = framework_tokens / input_tokens
Cost per command          = (input_tokens × price) / commands_used

framework_tokens is an estimated context footprint — computed at Stop time by scanning all .md files in agents/, skills/, domains/, governance/, and projects/ and dividing character count by 4. This measures possible context size, not exact injected tokens. Use it as a relative heuristic, not an absolute cost figure.

Setup: Copy .claude/settings.json.template to .claude/settings.json and update the hook paths to match your local installation. See docs/setup/.


Workspace Structure

syntran-aieos/
├── CLAUDE.md              ← Kernel: OS instructions, loaded every session
├── README.md              ← This file
├── CHANGELOG.md           ← Version history
├── CONTRIBUTING.md        ← Contribution guidelines
├── SECURITY.md            ← Governance model scope and limits
├── LICENSE
├── governance/            ← Safety model, approval templates, operating procedures
├── agents/                ← Specialist role contracts
├── skills/                ← Execution workflow definitions
├── domains/               ← Domain knowledge packs
│   ├── local-inference/   ← Ollama config, model guide, routing rules
│   ├── documentation/     ← Style guide, Diátaxis taxonomy
│   ├── testing-framework/ ← Core testing concepts, level taxonomy
│   ├── frontend-react-testing/
│   ├── backend-api-testing/
│   ├── data-ai-testing/
│   └── release-governance/
├── projects/              ← Tenant project profiles
│   ├── winfoldershift/
│   └── syntran-vscode/
├── examples/
│   └── projects/          ← Example and template project profiles
│       ├── _template/     ← Blank scaffold for a new project
│       ├── etl-pipeline/  ← Example: data pipeline project
│       └── api-service/   ← Example: API service project
├── scripts/
│   ├── sync-global-commands.ps1  ← Propagates synw-* commands to ~/.claude/commands/
│   ├── scaffold-testing-team.ps1 ← Installs testing team pack into a framework folder
│   ├── test_ollama.py             ← Smoke test for local Ollama inference
│   └── telemetry/         ← Hook scripts (log_prompt.ps1, log_command.ps1, log_stop.ps1)
├── templates/             ← Reusable scaffolds
│   └── testing/           ← Test plan, test case, defect report, release checklist
└── docs/                  ← System-level documentation

Scripts

Operational scripts live in scripts/.

ScriptPurposeDocs
sync-global-commands.ps1Copies all synw-* slash commands to ~/.claude/commands/ so they are available in every projectdocs/setup/sync-global-commands.md
scaffold-testing-team.ps1Copies testing team files into a target framework folder—
test_ollama.pyHealth check and smoke test for local Ollama inference—
telemetry/log_prompt.ps1Hook: logs every user message to telemetry/usage.csv—
telemetry/log_command.ps1Hook: logs every agent/skill invocation—
telemetry/log_stop.ps1Hook: logs token counts at session end—

Run after any command update:

& ".\scripts\sync-global-commands.ps1"

What Claude Cannot Do Autonomously

These are hard stops — no governance category overrides them:

  • Deploy anything to any environment
  • Create, rotate, or store secrets
  • Delete files without explicit approval
  • Modify auth or permission models silently
  • Push to remote repositories without explicit instruction
  • Execute any destructive workflow

Roadmap

ItemPriorityNotes
examples/projects/_template/DoneBlank scaffold for new project onboarding
LicenseDoneApache 2.0
Contribution guidelinesDoneFramework grows with owner's projects
ChangelogDoneStart when v1.0 is declared
LiteLLM routing layerLowPhase 2 — unified proxy for local/cloud
Additional agentsBacklogData Engineer, Cloud Engineer candidates

Runtime

v1 is Claude-first. Claude Code is the designed and tested execution engine. The inference routing layer (Ollama + Claude API) is already in place as a foundation, but multi-runtime support is a Phase 2 concern. Don't generalize prematurely — make v1 work well before abstracting the runtime.


Platform: Windows-first · Runtime: Claude Code (v1) · Governed by CLAUDE.md

Ver o original no GitHub

Bom para

Relacionados