Imported from hntehnte-commits/harness-template (AGENTS.md). Install upstream with npx skills add hntehnte-commits/harness-template. Copyright stays with the author.

Agent Context Manifest (AGENTS.md)

This file provides the AI Agent (Orchestrator) with the global context of the project, including where to find source code and how the harness is structured.

1. Project Information

• Project Name: My AI Harnessed Project
• Active Profile / Stack: python
• Test Command: pytest
• Lint Command: flake8
• Source Code Location: /src/ (Update this to point to your real source code directory)
• Tests Location: /tests/ (Update this to point to your real tests directory)

2. How the Harness Works

This project is governed by a Multi-Agent Prompt Harness located in /.opencode/. The AI agent never acts freely — it adopts specific roles to perform tasks, driven by a finite state machine stored in state.yaml.

2.1. State Machine (state.yaml)

The file /.opencode/artifacts/current_run/state.yaml tracks every execution. It contains:

• current_phase: One of Initialization, Contract, Implementation, Audit, Documentation, Complete
• active_agent: The current role (orchestrator, planner, developer, python-developer, embedded-developer, javascript-developer, qa, docs)
• plan_approved: Boolean — whether the Planner's deliverables have been validated
• active_profile: Which developer profile is in use
• task_checklist: List of {task, status} items tracking progress
• test_status: unknown, passing, or failing
• last_error: Description of the last error, if any

All agents read and write state.yaml directly using their file tools. No CLI scripts or Python code should be used for state transitions — the AI writes the YAML file itself.

2.2. Lifecycle (Phase Progression)

The Orchestrator reads state.yaml and advances through these phases:

1. Initialization / Contract → Planner Agent creates three deliverables:

   • /.opencode/artifacts/current_run/02_specification.yaml — requirements with AC-XXX IDs
   • /.opencode/artifacts/current_run/03_design.yaml — design with implements_ac links to AC-XXX
   • /.opencode/artifacts/current_run/implementation_plan.md — step-by-step plan

2. Implementation → Developer Agent (python, embedded-c, or javascript variant) executes TDD (section 2.3), writes production code, and tags every test with the AC-XXX it covers. After completing all features, updates test_ids in 02_specification.yaml.

3. Audit → QA Agent runs two checks:

   • Spec Coverage Audit (always runs): verifies every AC-XXX has at least one tagged test
   • Test Execution (skipped if bypass_qa_execution: true in config.yaml): runs the suite
   • If spec deviation is found, QA transitions directly to Planner (no Orchestrator involved)

4. Documentation → Docs Agent generates walkthrough, updates lessons learned.

5. Complete → Final state. Project is done.

2.3. Strict TDD Cycle

The Developer Agent follows three phases for every feature:

Tests must include the AC-XXX ID they cover (e.g., test_feature_x_ac_001.py or via pytest markers with ac_001). After all features are done, the developer updates test_ids in 02_specification.yaml to reflect what's covered.

2.4. Agent Transition Mechanism

Agents do not call each other by Python scripts. Instead, every agent ends its work by outputting a directive line:

--> NEXT ROLE: <agent_name>

The Orchestrator reads this output, updates state.yaml (active_agent, current_phase), then loads the corresponding agent file from /.opencode/agents/.

Exception: The QA Agent can transition directly to Planner when it detects spec deviation, without returning control to the Orchestrator.

2.5. Profiles System

The harness supports multiple technology stacks simultaneously. Active profiles are configured in /.opencode/profiles_enabled.yaml:

• core: Universal skills (TDD, git, state-management, skill-creator) — always loaded
• python: Python-specific skills (clean architecture, performance optimization, testing)
• embedded-c: Embedded C skills (AUTOSAR, memory analysis, TRACE32, compilation, deep reasoning)
• javascript: JavaScript/TypeScript skills (quality, async state, strict safety)

Only skills for active profiles are compiled into /.opencode/skills/, saving context window space. To enable a profile, edit profiles_enabled.yaml and re-run the harness compilation.

2.6. Memory System

Two files persist information across sessions:

• /.opencode/memory/architecture_decisions.md: Static constraints, architectural rules, design decisions. The AI must always respect these — they are never deleted.
• /.opencode/memory/lessons_learned.md: Dynamic memory. The QA Agent records bugs, gotchas, and fixes discovered during audits. Future sessions read this to avoid repeating past mistakes.

2.7. Skill System

Skills are modular instruction sets, one per directory under /.opencode/skills/<name>/SKILL.md. When assigned a task, the Orchestrator should read the relevant skill's SKILL.md before delegating to the sub-agent. Key skills include:

• strict-tdd-gatekeeper: Enforces RED → GREEN → REFACTOR discipline with AC-XXX test tagging
• state-management: Teaches how to read and write state.yaml directly using file tools
• git-management: Safe git commit/push protocols for multi-repo environments
• skill-creator: How to create new skills from chat history or repetitive procedures
• file-translator: How to translate files between formats
• Profile-specific skills: Python (clean architecture, performance, testing), Embedded C (AUTOSAR, memory, compilation, TRACE32, deep reasoning)

2.8. Available Sub-Agents (Roles)

• Developer Agent (/.opencode/agents/developer.md)
• Documentation Agent (/.opencode/agents/docs.md)
• Embedded Developer Agent (/.opencode/agents/embedded-developer.md)
• Javascript Developer Agent (/.opencode/agents/javascript-developer.md)
• Orchestrator (/.opencode/agents/orchestrator.md)
• Planner Agent (/.opencode/agents/planner.md)
• Python Developer Agent (/.opencode/agents/python-developer.md)
• QA Agent (/.opencode/agents/qa.md)

Available Skills

• AUTOSAR Software Architecture (/.opencode/skills/autosar-software-architecture/SKILL.md)
• C Memory Analyzer (Profile Specific) (/.opencode/skills/c-memory-analyzer-profile-specific/SKILL.md)
• Compilation and Analysis (/.opencode/skills/compilation-and-analysis/SKILL.md)
• Embedded Deep Reasoning (/.opencode/skills/embedded-deep-reasoning/SKILL.md)
• Python Clean Architecture (/.opencode/skills/python-clean-architecture/SKILL.md)
• Python Performance Optimization (/.opencode/skills/python-performance-optimization/SKILL.md)
• Python Testing and Quality (Profile Specific) (/.opencode/skills/python-testing-and-quality-profile-specific/SKILL.md)
• TRACE32 CMM Scripting (/.opencode/skills/trace32-cmm-scripting/SKILL.md)

3. Memory & Artifacts

The Orchestrator and sub-agents must read from and write to these locations to maintain state:

• State Machine (Artifacts): /.opencode/artifacts/current_run/ (Contains state.yaml and task deliverables).
• Long-Term Memory: /.opencode/memory/architecture_decisions.md (Constraints and rules).
• Dynamic Memory: /.opencode/memory/lessons_learned.md (Gotchas and past mistakes to avoid).

4. Initialization

4.1. First Load — No Prior State

If state.yaml does not exist, the AI was loaded for the first time with no previous plan:

1. Read this AGENTS.md to understand the project layout.
2. Read /.opencode/skills/state-management/SKILL.md to learn state manipulation.
3. Read /.opencode/artifacts/templates/state_schema.yaml as the format reference.
4. Capture the user's request — whatever the user just asked for IS the task.
5. Read /.opencode/agents/orchestrator.md to assume the Orchestrator role.
6. Create state.yaml from scratch, using the schema template as a base:
   • current_phase: "Initialization"
   • active_agent: "orchestrator"
   • active_profile detected from workspace files (see orchestrator.md step 3.3)
   • task_checklist with the user's request as the first task
7. Proceed with Initialization phase (analyze workspace, detect profile, transition to Planner).

4.2. Subsequent Loads — State Exists

If state.yaml already exists:

1. Read this AGENTS.md to understand the project layout.
2. Read /.opencode/agents/orchestrator.md to assume the Orchestrator role.
3. Read /.opencode/skills/state-management/SKILL.md to learn how to manipulate state.yaml.
4. Read /.opencode/artifacts/current_run/state.yaml to see the current phase and agent.
5. Resume from where the last session left off.