convez.ai
AgenteAutomaçãoAvançado
seokan-jeong

Team Shinchan – Orquestrador de Agentes com Guardrails

seokan-jeong/team-shinchan

15 agentes especialistas com guardrails, qualidade e aprendizado contínuo

Ver no GitHub
BomPluginScore · de 0 a 100

Harness de multi-agentes que estrutura 15 especialistas em IA para debater, planejar, executar e aprender dentro de limites bem definidos. Implementa guardrails, controle de budget de tokens, ontologia de projeto, gates de qualidade e rastreabilidade completa de ações, transformando agentes impredizíveis em sistemas confiáveis.

Instalação

$npx convez-ai seokan-jeong/team-shinchan

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
9
Forks
2
Acompanhando
1
Saúde
57%
Último commit
há 3 meses
Versão
v4.58.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Orquestração de agentes em projetos de desenvolvimento sem deixar controle
  • Automação de ciclos de desenvolvimento (planejar → executar → revisar → aprender)
  • Auditoria e rastreabilidade de decisões de IA em produção
  • Controle de custos e consumo de tokens em sistemas multi-agentes

Veredito

Projeto ambicioso e bem pensado para quem trabalha com agentes Claude em escala. Traz conceitos sólidos de engenharia (guardrails, ontologia, budget control) que resolvem problemas reais. Recomendado para times que precisam de confiabilidade e observabilidade em sistemas multi-agentes.

README

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

Team-Shinchan

The Agent Harness for Claude Code

Guardrails, Observability, Ontology, and Quality Gates for AI-Powered Development

15 specialist agents with structured workflows, project ontology, budget controls, analytics, and self-learning.

Version License Claude Code GitHub stars

Try It | Features | Commands | The Team


Why an Agent Harness?

AI agents are powerful but unpredictable. Without constraints, they hallucinate architecture, skip reviews, blow through token budgets, and forget past decisions. An Agent Harness solves this by wrapping agents in guardrails, quality gates, and feedback loops -- the same way a test harness wraps code in assertions.

Team-Shinchan turns Claude Code into a harnessed multi-agent system where 15 specialists debate, plan, execute, and learn -- all within well-defined boundaries.

Without a HarnessWith Team-Shinchan
Agent starts blind, re-reads the whole codebaseProject Ontology auto-builds a knowledge graph on first session
Agents skip stages, jump to codeWorkflow Guard enforces stage-tool matrix
No visibility into agent behaviorAnalytics with trace IDs track every action
Unlimited token burnBudget Guard caps spend per session
No quality signal on the harness itselfHarness Lint checks plugin integrity
Past decisions forgottenMemory + Ontology + session bridging persist context
Code reviewed ad-hoc (or not at all)Action Kamen reviews every phase (mandatory)

Harness Engineering

Team-Shinchan is built on 5 Harness Engineering principles:

1. Context Engineering

Load the right knowledge at the right time.

  • load-kb hook injects project knowledge base at session start
  • Project Ontology auto-builds a knowledge graph of your codebase (entities, relations, dependencies)
  • AGENTS.md auto-generated map of all 15 agents with roles and capabilities
  • Session bridging via session-wrap and resume for cross-session continuity
  • Self-learning memory accumulates project conventions over time

2. Architectural Constraints

Hard boundaries that prevent structural drift.

  • Workflow Guard -- stage-tool matrix blocks code edits during planning (PreToolUse hook)
  • Layer Enforcement -- validator ensures agents stay in their architectural layer
  • Rules System -- 54 rules across coding (14), security (14), testing (13), git (13)
  • Stage-tool matrix -- 6 tools x 4 stages, enforced automatically

3. Guardrails and Quality Gates

Automated checks that prevent bad outcomes.

  • Security Hook -- blocks secrets, destructive git, sensitive files, large files
  • Budget Guard -- token budget enforcement with alerts at 80% and hard stop at 100%
  • Deny List -- 15 pattern rules blocking dangerous operations
  • Self-Check -- completion checklist all execution agents must pass
  • Action Kamen -- mandatory code review with Skepticism Rules (S1-S4) at every phase boundary
  • Sprint-Contract -- AC testability review before execution begins

4. Feedback Loops

Observability and continuous improvement.

  • Analytics -- trace IDs, event tracking, agent performance metrics (src/analytics.js)
  • Harness Lint -- static analysis of the harness itself (src/harness-lint.js)
  • ARCHITECTURE.md auto-generation -- src/gen-architecture-map.js generates agent hierarchy, workflow, invariant rules, and entry points; --check flag integrates into CI
  • Eval -- schema validation and regression detection (src/eval-schema.js, src/regression-detect.js)
  • Auto-Retrospective -- extracts learnings after every completed task
  • Garbage Collection -- lint detects orphaned skills, broken refs, stale configs

5. State Management

Durable state across sessions and workflows.

  • WORKFLOW_STATE.yaml -- structured state file with stage, phase, and progress
  • Trace IDs -- every agent action tagged for end-to-end traceability
  • Session Wrap -- auto-summary on session end, persisted to work tracker
  • Resume -- interrupted workflows resume from last checkpoint with handoff artifacts
  • Work Tracker -- JSONL event log with auto-rotation at 10K lines

What's New

v4.23.0 — Generator-Evaluator Harness Strengthening

Benchmarked from Anthropic's "Harness Design for Long-Running Apps":

  • Sprint-Contract pattern — Nene and Action Kamen negotiate testable AC criteria before execution. Shinnosuke mediates the review with audit logs.
  • Skepticism Rules S1-S4 — Action Kamen now runs Evidence Gate, Assumption Audit, Coverage Traceability, and Regression Guard on every review.
  • Pre-compact handoff — Context resets preserve progress, decisions, and blocking issues. /resume auto-loads handoff state.
  • Test Execution Mode — Action Kamen can run declared test commands and attach output as evidence (run_tests: true).
  • Spec Granularity Rules — 3 rules (Deliverable Anchor, Binary Verifiability, Command Evidence) enforce testable AC writing.
  • Structured rubrics — eval-rubrics.json with default/documentation/planning rubrics for machine-readable quality scoring.
  • Assumption Audit — Harness Lint verifies structural assumptions (Skepticism Rules, Sprint-Contract, rubrics, handoff) haven't drifted.

v4.22.0 — AK Review Gate for Requirements and Planning

  • Action Kamen auto-review gates after user approval of REQUESTS.md and PROGRESS.md
  • Hard block with max 2 auto-revise retries before user escalation

Earlier Highlights

  • v4.18.0: Domain-aware routing, collaboration scoring, wave parallel execution
  • v4.17.0: Plan Mode integration, token usage tracking, git commit deferred to Stage 4
  • v4.10.0: ARCHITECTURE.md auto-generation, 3-layer ontology, agent self-observation
  • v4.9.0: Brainstorm skill, Socratic interview, two-stage review
  • v4.2.0: 18 enforcement gaps closed — budget hard stop, stage transition gates
  • v4.0.0: Harness foundation — analytics, trace IDs, budget guard, 5-layer architecture

Try It in 2 Minutes

Install

From Marketplace (Recommended)

/plugin marketplace add seokan-jeong/team-shinchan
/plugin install team-shinchan

One-Click Install

curl -fsSL https://raw.githubusercontent.com/seokan-jeong/team-shinchan/main/install.sh | bash

Manual Install

git clone https://github.com/seokan-jeong/team-shinchan.git ~/.claude/plugins/team-shinchan

Verify Installation

/team-shinchan:help

If you see the help menu, you are ready to go.

What's Next?

  • Read the Getting Started Guide
  • Try /team-shinchan:brainstorm {problem} to explore before building
  • Try /team-shinchan:start {your task} to see the full workflow
  • Use /team-shinchan:debate for design decisions

15 Specialized Agents

Orchestration

AgentRole
ShinnosukeOrchestrator
HimawariAtlas (Large Projects)
MidoriDebate Moderator

Execution

AgentRole
BoExecution PO
KazamaDeep Worker

Specialists

AgentRole
AichanFrontend/UI
BuriburiBackend/API
MasaoDevOps/Infra

Advisors

AgentRole
HiroshiSenior Oracle
NeneStrategic Planner
MisaeRequirements Analyst
Action KamenCode Reviewer

Utility

AgentRole
ShiroFast Explorer
MasumiDocumentation
UmeImage/PDF Analysis

Commands

49 commands across workflow, specialist, and utility categories:

Workflow Commands

CommandDescription
/team-shinchan:startStart integrated workflow
/team-shinchan:resumeResume interrupted workflow
/team-shinchan:autopilotAutonomous execution
/team-shinchan:ultraworkParallel execution
/team-shinchan:ralphLoop until complete
/team-shinchan:orchestrateOrchestrate multi-agent task
/team-shinchan:bigprojectLarge project with Himawari
/team-shinchan:statusShow workflow status

Analysis and Planning

CommandDescription
/team-shinchan:brainstormExplore problem space before requirements
/team-shinchan:debateTrigger expert debate (via Midori)
/team-shinchan:planPlanning session
/team-shinchan:analyzeDeep analysis
/team-shinchan:deepsearchCodebase search
/team-shinchan:requirementsGather and clarify requirements
/team-shinchan:researchResearch a topic
/team-shinchan:design-reviewCompare design mockups against implementation to detect UI mismatches

Implementation

CommandDescription
/team-shinchan:implementExecute code changes
/team-shinchan:frontendFrontend/UI development
/team-shinchan:backendBackend/API development
/team-shinchan:devopsInfrastructure and DevOps
/team-shinchan:reviewCode review
/team-shinchan:visionImage/PDF analysis
/team-shinchan:micro-executeMicro-task execution with per-task two-stage review
/team-shinchan:systematic-debugging4-phase root-cause debugging (investigate, analyze, hypothesize, implement)
/team-shinchan:test-driven-developmentEnforce RED-GREEN-REFACTOR TDD cycle during implementation

Verification

CommandDescription
/team-shinchan:verify-implementationRun full verification suite
/team-shinchan:verify-agentsVerify agent schema
/team-shinchan:verify-skillsVerify skill files
/team-shinchan:verify-consistencyVerify cross-references
/team-shinchan:verify-workflowVerify workflow state
/team-shinchan:verify-memoryVerify memory system
/team-shinchan:verify-budgetVerify token budget

Harness and Ontology

CommandDescription
/team-shinchan:ontologyQuery, manage, and visualize project ontology
/team-shinchan:impact-analysisCascade dependency analysis with risk assessment
/team-shinchan:analyticsView agent analytics and trace data
/team-shinchan:budgetCheck token budget status
/team-shinchan:lint-harnessLint the harness for structural issues
/team-shinchan:evalRun eval checks and regression detection

Memory and Utility

CommandDescription
/team-shinchan:memoriesView learned memories
/team-shinchan:learnAdd to memory
/team-shinchan:forgetRemove memory
/team-shinchan:work-logQuery work tracker events
/team-shinchan:session-summaryView session summary
/team-shinchan:manage-skillsManage plugin skills
/team-shinchan:helpShow help
/team-shinchan:setupFirst-time setup and health check
/team-shinchan:setup-hudConfigure Claude Code statusLine HUD display

Internal / Admin Commands

CommandDescription
/team-shinchan:releaseBump version across plugin.json, marketplace.json, README, and CHANGELOG (maintainers only)
/team-shinchan:verification-before-completionBlock completion claims without fresh verification evidence (auto-invoked by agents)

Quick Triggers

No commands needed -- just say:

Say ThisActivates
"ulw", "fast", "parallel"Ultrawork (parallel mode)
"until done", "complete it"Ralph (persistence mode)
"autopilot", "auto"Autopilot (autonomous)
"brainstorm", "explore"Brainstorm (problem exploration)
"debate", "pros and cons"Debate system
"analyze", "debug", "why"Deep analysis

How Skills Work

Skills are not just documentation -- they automatically invoke specialist agents.

/team-shinchan:brainstorm  (optional — explore problem space)
       |
       v
/team-shinchan:start
       |
       v
+--------------------------------------+
|  Task(subagent_type="shinnosuke")    |  <- Auto-invoked
+------------------+-------------------+
                   v
+--------------------------------------+
|  Shinnosuke orchestrates:            |
|  +-- Misae (Socratic requirements)   |
|  +-- Nene (planning)                 |
|  +-- Shiro (exploration)             |
|  +-- Bo(PO) → domain agent →         |
|       Action Kamen (2-stage review)  |
|  +-- Masumi (completion docs)        |
+--------------------------------------+
SkillAuto-Invokes
/startShinnosuke -> Full workflow
/brainstormHiroshi -> Problem exploration
/planNene -> Structured planning
/analyzeHiroshi -> Deep analysis
/deepsearchShiro -> Masumi
/debateMidori -> Expert panel
/autopilotShinnosuke -> Autonomous mode
/ultraworkShinnosuke -> Parallel execution
/ralphKazama -> Persistent loop
/implementBo -> Code execution
/frontendAichan -> Frontend/UI
/backendBuriburi -> Backend/API
/devopsMasao -> Infrastructure
/reviewAction Kamen -> Code review
/requirementsMisae -> Requirements analysis
/bigprojectHimawari -> Large project orchestration
/ontologyOntology engine -> Knowledge graph
/impact-analysisOntology engine -> Dependency cascade

You run the skill, agents do the work.


Plugin Inventory

ComponentCountLocation
Agents15agents/
Skills50skills/
Commands49commands/
Hooks30 entrieshooks/
Validators24tests/validate/
Rules4 categories (54 rules)rules/
Src Scripts16src/

Quality and Testing

Team-Shinchan is validated by 3 tiers of automated testing:

TierTestsWhat It Checks
Static Validators24Schema, cross-refs, consistency, API contracts, token budget, layer enforcement, agents-map, ontology integrity, hook execution
Agent Behavior (promptfoo)29Individual agent role adherence
E2E Workflow11Full workflow scenarios (5 types)
# Run static tests locally (free, no API key)
./run-tests.sh static

# Run all tests (requires ANTHROPIC_API_KEY)
./run-tests.sh all

Dashboard

Team-Shinchan ships with a live workflow dashboard served on http://127.0.0.1:8765/ from src/dashboard/server.js. It streams ontology updates, workflow state transitions, and analytics events over Server-Sent Events.

Dashboard auto-spawn

Starting with v4.37.0 the dashboard auto-starts on Claude Code SessionStart and persists across sessions as a permanent daemon. Behavior:

  • Singleton enforcement -- a lockfile at ~/.shinchan/dashboard.lock (format <pid> <port>) combined with a /health probe ensures exactly one daemon runs at a time. Stale lockfiles (dead PID) are auto-cleared and re-spawned on the next session.
  • Fixed port 8765 -- no port negotiation; collisions are arbitrated by the dashboard server's EADDRINUSE throw.
  • First-spawn browser open -- the first session that actually spawns the daemon opens your default browser to http://127.0.0.1:8765/ (best-effort on macOS / Linux / Windows via open / xdg-open / start). Subsequent sessions silently attach and never open a browser tab.
  • Hook isolation -- failures in the autostart hook never block other SessionStart hooks (write-tracker, session-init, ontology-auto-build).

Opt out

Two opt-out channels, with env wins precedence:

ChannelValueEffect
TS_DASHBOARD_AUTOSTART env var0, false, off (case-insensitive)Skip autostart for this session
TS_DASHBOARD_AUTOSTART env varany other defined valueForce-enable (skips setting fallback)
.claude-plugin/plugin.json settings.dashboard_autostartfalsePermanent opt-out across sessions
defaulttrueAutostart enabled
# Disable for a single Claude Code session
TS_DASHBOARD_AUTOSTART=0 claude

# Permanent opt-out: edit .claude-plugin/plugin.json
#   "settings": { "dashboard_autostart": false }

Stop the daemon

npm run dashboard:stop

Sends SIGTERM to the daemon PID recorded in the lockfile, unlinks the lockfile, and exits cleanly. Idempotent: a second invocation with no daemon running prints no lockfile -- dashboard not running and exits 0.

Logs

Daemon stderr is appended to ~/.shinchan/dashboard.log. Log rotation is not implemented -- if the file grows large, truncate it manually (: > ~/.shinchan/dashboard.log) or after stopping the daemon (npm run dashboard:stop && rm ~/.shinchan/dashboard.log). Automatic rotation may ship in a future workflow.


FAQ

Does this replace Claude Code?

No. Team-Shinchan is a plugin that enhances Claude Code by adding specialized agents, guardrails, and observability. You still use Claude Code as normal, but now with harnessed agents instead of one generalist.

Is it free?

Yes, Team-Shinchan is MIT licensed and free to use. Agent calls consume your Claude Code API credits (same as any other Claude conversation). The Budget Guard helps you control spend.

How many API calls does it make?

Quick fixes: ~3 calls (Bo implements -> Action Kamen reviews -> done) Standard tasks: 10-30 calls (requirements -> planning -> execution -> completion) Complex tasks with debates: 20-50 calls (includes expert panel discussions)

Each call is purposeful, traced, and documented in the workflow.

Can I use individual agents without the full workflow?

Yes. Each skill works standalone:

  • /team-shinchan:analyze -> Just Hiroshi (deep analysis)
  • /team-shinchan:plan -> Just Nene (planning)
  • /team-shinchan:deepsearch -> Just Shiro + Masumi (search)

Or let Shinnosuke orchestrate the full workflow with /team-shinchan:start.


Credits

Inspired by and built upon:


License

MIT License


Team-Shinchan -- The Agent Harness for Claude Code

Guardrails, Observability, and Quality Gates for AI-Powered Development

Ver o original no GitHub

Bom para

Relacionados