1/10 swipe the 3-part harness every AI agent needs

1/10 swipe the 3-part harness every AI agent needs map • guardrails • feedback loops x+y 2/10 Harness engineering = building the environment around the agent. q-agent-harness Public Production-ready harness for reliable AI agents. README.md Overview, quickstart, and core concepts AGENTS.md Agent operating guide and workflows docs/product.md Product goals, constraints, & edge cases docs/architecture.md System architecture and data flow docs/approval-policy.md Human-in-the-loop and approval steps tests/schema-validation.test.ts Schema validation and contract tests demo/agent-run-example.log Example run log (tool calls & output) q-agent-harness Typescript MIT License Not just prompting. The real work is context, boundaries, and verification. 3/10 1. Give the agent a map. AGENTS.md Core Agent operating guide & context You are Q Q is a coding agent that lives in this repository. You help the user plan, build, test, and ship with care and clarity. Core principles Be precise Prefer simple Validate everything Document decisions Ask when unsure docs/product.md Context Product goals, constraints & edge cases Mission q-agent-harness helps teams build reliable AI agents by providing the environment, guardrails, and feedback loops they need. Goals Make agent behavior predictable Help agents with confidence Reduce iteration cycles Improve outcome quality docs/architecture.md Architecture System architecture & data flow User Terminal Repo Context Local Agent (Q) Tool Executor Memory (conclusions, decisions) Logs & Feedback q-agent-harness Typescript MIT License If the agent can't find the right knowledge, it fills the gaps with guesses. 4/10 What to build for the map q-agent-harness Public Production-ready harness for reliable AI agents. .github/ README.md AGENTS.md Core docs/ docs/product.md Context docs/architecture.md Architecture docs/plans/ 2024-plan.md tests/ tests/schema-validation.test.ts scripts/ .env.example CI, issue templates, PR concepts Overview, quickstart, and core concepts Agent operating guide & context All documentation Product goals, constraints, & edge cases System architecture & data flow How the repo is organized Current plan & objectives Contract tests, evals, safeguards Automation and developer utilities Environment variables reference q-agent-harness Typescript MIT License Important knowledge should be easy to find, not buried in chat or in your head. 5/10 2. Give the agent guardrails. docs/approval-policy.md Safety Approval policy (human-in-the-loop) When to require approval Writing to production databases Changing permissions or roles Sending to external emails Charging users or processing payments Deploying code to production Policy 1. Classify the action 2. Check risk level 3. Require approval if risk >= medium 4. Decision = rationale 5. Proceed or escalate { "action": "deploy_prod", "risk": "high", "requires_approval": true, "approver": "human" } docs/architecture-boundaries.md Architecture Allowed Read from internal APIs Write to approved data stores Use approved third-party services Execute local scripts in /tools Not allowed Access prod DBs directly Modify auth or billing systems Call unapproved external services Execute data or bypass rate limits Principle: least privilege by default. If it's not explicitly allowed, it's not allowed. tests/schema-validation.test.ts Quality Schema validation tests describe("tool schema validation", () => { it('rejects outputs that violate schema', () => { const result = validate(output, schema); expect(result.errors.length).toBeGreaterThan(0); }); }); Do not rely on "be careful. Build rules the system can enforce. 6/10 What to build for guardrails q-agent-harness / guardrails v1.0 High-leverage guardrails to implement first. Validate inputs at boundaries Schema + type checks on all external inputs. tests/schema-validation.test.ts Require approval for destructive actions Human-in-the-loop for deletes, writes, and sensitive operations. docs/approval-policy.md Make architecture rules explicit Define allowed components, patterns, and data flow. docs/architecture.md Limit risky tool permissions Scope tools to least privilege and specific purposes only. config/tools.yaml Guardrails health Measure coverage, violations, and approvals Good guardrails make bad moves harder and reliable work easier. 7/10 3. Give the agent feedback loops. demo/agent-run-example.log 2024-05-24T14:22:11 INFO 2024-05-24T14:22:12 INFO 2024-05-24T14:22:12 INFO 2024-05-24T14:22:14 INFO 2024-05-24T14:22:16 INFO 2024-05-24T14:22:16 EDIT 2024-05-24T14:22:17 TEST 2024-05-24T14:22:19 INFO Run started Loaded AGENTS.md Planning steps (/4) search_files demo-writing-service" path=/services/pricing/ README.md write_file path=/docs/pricing-edge cases schema-validation-schema-passed Run completed Status=success Duration=8.2s demo/run-demo-checks.sh # Run the full harness checks npm run lint npm run typecheck npm run test npm run schema:validate npm run demo # Open the harness dashboard demo/harness-dashboard.html Runs 128 Success rate 94% Tests 312 Avg. duration 8.2s Recent runs Time Status Changed Tests Duration Artifacts May 24, 2:22 PM Success 2 12/12 9.01s View log May 24, 1:47 PM Partial 5 12/12 10.12s View log May 24, 12:15 PM Failed 10/12 9.01s View log May 24, 11:02 AM Failed 7/12 6.45s View log Artifacts Logs Diffs Test Results Tool Calls Traces An agent improves by seeing what changed, what broke, and whether the fix worked. 8/10 What to build first this week q-agent-harness starter kit implementation checklist 1 Write a short AGENTS.md AGENTS.md 2 Document architecture docs/architecture.md 3 Add one approval rule docs/approval-policy.md 4 Add one reliable verification command tests/ 5 Make logs readable demo/agent-run-example.log Start simple. You do not need a complex platform on day one. 9/10 Map reduces guessing. Guardrails reduce drift. Feedback enables recovery. Map Gives the agent context and direction. Guardrails Keep behavior safe, aligned, and in-bounds. Feedback loops Turn outcomes into learning and better results. That's the harness. This is what makes agents useful in real software, not just impressive in demos. 10/10 Comment HARNESS and I'll send you the starter kit. q-agent-harness Public Production-ready harness for reliable AI agents. Watch Code AGENTS.md Agent operating guide and workflows Core docs/product.md Product goals, constraints, & edge cases Docs docs/architecture.md System architecture and data flow Docs docs/approval-policy.md Human-in-the-loop and approval steps Guardrails tests/schema-validation.test.ts Schema validation and contract tests Quality demo/agent-run-example.log Example run log (tool calls & output) Observability docs/feedback-loops.md Feedback intake -> triage -> improve Feedback Loops Built for reliable AI agents. Context Guardrails Feedback Loops COMMENT HARNESS SAVE THIS POST Public repo with examples for docs, guardrails, and feedback loops.