team-shinchan

---

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 Harness	With Team-Shinchan
Agent starts blind, re-reads the whole codebase	Project Ontology auto-builds a knowledge graph on first session
Agents skip stages, jump to code	Workflow Guard enforces stage-tool matrix
No visibility into agent behavior	Analytics with trace IDs track every action
Unlimited token burn	Budget Guard caps spend per session
No quality signal on the harness itself	Harness Lint checks plugin integrity
Past decisions forgotten	Memory + 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