Skip to content

Instantly share code, notes, and snippets.

@mer0mingian

mer0mingian/agent_harness_resources.md

Last active April 13, 2026 22:27
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mer0mingian/78b86a60cb35efe4a163e88129f900a0 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mer0mingian/78b86a60cb35efe4a163e88129f900a0 to your computer and use it in GitHub Desktop.
Download ZIP
Daniel Agent Harness Resources
Raw
agent_harness_resources.md

OpenCode Upgrade

Plugins

OpenCode Plugins

For those activated, see opencode.json. For an overview, see the yaml.

My OpenCode Plugins

Containerisation & Security

Free model providers

Agent Workflow Definitions

For Quality Assurance I want to stick to the Agent Defintion best practices from this solution.

I am using chaining/learning via the subtask2-plugin, as described here.

Online Resources

Multi Agent-cli coordination

Pre-existing Agent Workflow Extensions/Plugins

Agent Memory

Markdown-based

Combined Local Markdown + DB

Full remote DBs

  • Overview - Mem0 - This is the global user knowledge. To run on my RPi. the most mature solution
  • mem0 - monorepo for the full ecosystem most mature solution I have seen so far
  • jojopdq/HiMem off-shoot/rework of mem0 --> not ready for work
  • BAI-LAB/MemoryOS

Further Research

Harness Engineering

Tooling

Skills & CLI Tools

MCP Rag Server

Other

Raw
daniels_feat_dev_workflow.md

Daniel's SDD workflows

List of Workflows/Commands a la subtask2:

  1. New Feature (set) - Feat Specification, Solution Deisign, Tech Refinement, Implementation
  2. Github Issue Bug fix [tbd]
  3. Create deepwiki architecture docs [tbd]
  4. Deep web research [tbd]
  5. Codebase review and simplification [tbd]

New Feature Workflow Description

The entire workflow should be managed by an Workflow-Orchestrator agent. All agents should have some base skills like rtk, verification-before-completion, git-advanced-workflows, solid, system-design, using-git-worktrees, python-environment, finishing-a-development-branch.

Stage 1: Feature Specification

  1. Specification Agent: If not existing, define project/product summary (Goal, Tech Stack, Users, Scale...).
  2. Specification Agent: Create Feature(set) specification by interview or from Markdown. Can live in github issues, if that was used by user, or in local markdown. Needs skills for gh cli, openspec, product-spec-formats, brainstorming.
  3. Critical-Thinking-Agent: Have AI validate that Feature(set) specification is unambiguous, complete, covers all corner cases. This agent excels in critical thinking! Ask-questions-if-underspecified skill.
  4. Specification Agent: Translate the Feature(set) specification into openspec format.
  5. Specification Agent: Document in Business Documentation. Translate into testable User Stories. Those should live with the specs (github issue/markdown).
  6. Workflow-Orchestrator: Have the user review/revise the specs and stories.

Stage 2: Solution Design

  1. Architect Agent: Document Solution Design (changes). This includes C4-description, tech stack, schemata for data exchange. Based on openspecs and user stories.
  2. Workflow-Orchestrator: Review and revise by user.
  3. 4 C4-Agents: Sequentially Document each C4-level in Technical Documentation. If C4-doc does not exist yet, invoke tool for deepwiki-rs (smart-docs skill).

Stage 3: Technical Refinement

  1. Architect Agent: Create a Delivery Plan which breaks implementation down into (Milestones, if big, and) Tasks.
  2. Critical-Thinking-Agent: Validate Tasks conciseness and completeness.
  3. Workflow-Orchestrator: Determine if parallel or sequential work is better (branching vs. worktrees). Manage git setup.
  4. Workflow-Orchestrator: Assign the best available agent per task, give them a detailed prompt with optimal context (boundaries, tech stack, best practices, available docs).
  5. Workflow-Orchestrator: Have the user review/revise the Delivery Plan.
  6. Have QA Agent(s) create e2e/integration tests for all User Stories for all cases. Must be exhaustive and cover all corner cases. This must be an isolated task from the next Stage. They need the SWE skills, but also e2e-testing, debugging, solid, webapp-testing, systematic-debugging.

Stage 4: Implementation

  1. Have SWE Agent(s) implement all tasks. Add/modify unit tests. Collect garbage code/tests. Make e2e/integration and unit test pass. Commit. Must never edit e2e/integration tests.
  2. Have task solution(s) reviewed by QA Agent(s) and revise if necessary.
  3. Have the SWE Agent(s) perform a mini retro: Update/correct skills and add examples, sticking to best practices.
  4. Have Workflow-Orchestrator Agent merge task solutions.
  5. Have Architect Agent review and SWE Agent(s) revise merges if necessary. Update docs. Update delivery plan.
  6. Create PR and summary by Architect Agent.
  7. Have Workflow-Orchestrator ask user to review/comment/merge.

Orginial Vertical Flow

Taken from this excellent Infoq article.

Raw
feat-dev-workflow-to-claude.md

Tried to translate, but with many flaws

1. CLAUDE.md

This is the main entry point. It defines the global environment and orchestrates the transition between the agents for each stage.

# Daniel's Feature Development Workflow Orchestrator

## Global Environment
- **Runtime**: Python >= 3.12
- **Package Manager**: `uv`
- **Type Checker**: `ty`
- **Lint/Format**: `ruff`
- **Infrastructure**: Terraform (AWS)
- **Contracts**: OpenSpec (OpenAPI)

## Sub-Agent Definitions
This workflow utilizes specialized sub-agents located in `.claude/agents/`:
1. **Product Manager Agent**: Discovery and Delivery.
2. **Lead Engineer Agent**: Research, Architecture, Design, and Approval.
3. **Infrastructure Engineer Agent**: Provisioning and IaC.
4. **Software Engineer Agent**: Implementation and PR creation.
5. **Quality Assurance Agent**: Verification and Acceptance.

## Execution Rules
- Never skip a stage.
- Documentation must follow the **Maturity Levels** (L1-L5).
- Every Python change must pass `uv run ruff check` and `uv run ty .`.
- Use `/develop-feature` to initiate the full cycle.

2. .claude/commands/develop-feature.md

This defines the custom command that maps the gist stages to the agents.

# Command: /develop-feature <jira_ticket_id>

## Stage 1: Discovery
- **Product Manager Agent**: Fetch and analyze Jira ticket `$1` for format compliance.
- **Product Manager Agent**: Search Confluence for existing documentation.
- **Lead Engineer Agent**: Research codebase and identify implementation patterns.

## Stage 2: Design
- **Lead Engineer Agent**: Analyze/Update Draw.io diagrams (via mermaid-skill).
- **Lead Engineer Agent**: Draft/Update OpenSpec definitions in `openapi.yaml`.

## Stage 3: Infrastructure
- **Infrastructure Engineer Agent**: Create/Modify Terraform code to support OpenSpec.
- **Infrastructure Engineer Agent**: Execute `terraform validate` and `plan`.

## Stage 4: Implementation
- **Software Engineer Agent**: Implement Python 3.12 logic using `uv`.
- **Software Engineer Agent**: Run `uv run ruff check --fix` and `uv run ty .`.
- **Software Engineer Agent**: Ensure Pydantic models align with OpenSpec.

## Stage 5: Verification
- **Quality Assurance Agent**: Write and execute `pytest` suites.
- **Lead Engineer Agent**: Final review of code quality and architectural alignment.

## Stage 6: Delivery
- **Software Engineer Agent**: Create Bitbucket PR and link Jira ticket.
- **Product Manager Agent**: Update Jira status and inform stakeholders.

3. Agent Definitions (.claude/agents/*.md)

.claude/agents/product_manager_agent.md

# Product Manager Agent
**Role**: Requirements gatekeeper and delivery coordinator.
**Tools**: `jira_mcp`, `confluence_mcp`.
**Instructions**:
- Validate Jira tickets against "Job Story" or "User Story" templates.
- Ensure the "Acceptance Criteria" are clearly defined before handover.
- Update Confluence pages with high-level feature summaries.
- Handle external communication and Jira state transitions.

.claude/agents/lead_engineer_agent.md

# Lead Engineer Agent
**Role**: Architecture, OpenSpec design, and Quality Guard.
**Tools**: `filesystem`, `confluence_mcp`, `drawio_to_mermaid_skill`.
**Instructions**:
- Translate requirements into OpenSpec (OpenAPI) definitions.
- Review Draw.io diagrams to ensure architectural integrity.
- Oversee "Maturity Levels" compliance (ensuring repo reaches target L-level).
- Perform final type-safety checks using `ty`.

.claude/agents/infrastructure_engineer_agent.md

# Infrastructure Engineer Agent
**Role**: AWS Resource Provisioning.
**Tools**: `terraform_cli`, `aws_cli_mcp`, `filesystem`.
**Instructions**:
- Generate Terraform manifests following the project's modular structure.
- Ensure all resources (ALB, Lambda, S3) support the OpenSpec contract.
- Provide `terraform plan` output for review; do not apply changes.

.claude/agents/software_engineer_agent.md

# Software Engineer Agent
**Role**: Python Implementation Specialist.
**Tools**: `uv`, `ty`, `ruff`, `filesystem`, `bitbucket_mcp`.
**Instructions**:
- Implement logic in Python 3.12 with strict type hinting.
- Use `uv sync` to manage dependencies.
- Fix all `ruff` and `ty` errors before submitting.
- Create descriptive Bitbucket PRs referencing the Jira ID.

.claude/agents/quality_assurance_agent.md

# Quality Assurance Agent
**Role**: Verification and Testing.
**Tools**: `pytest`, `jira_mcp`, `filesystem`.
**Instructions**:
- Generate test cases derived directly from Jira Acceptance Criteria.
- Ensure 100% test coverage for new logic paths.
- Verify that the documentation in the repo matches the actual implementation.

4. Custom Skill: scripts/drawio_utils.py

To support the Lead Engineer Agent's requirement to handle diagrams:

import sys
import xml.etree.ElementTree as ET

def parse_drawio_to_mermaid(file_path):
    """
    Skill for Claude to read Draw.io XML and convert to Mermaid syntax
    to allow the Lead Engineer Agent to reason about architecture.
    """
    # Implementation logic to extract labels and connectors
    pass

if __name__ == "__main__":
    # Integration for Claude Code
    pass
Raw
maturity_levels.md

Checklist for AI-assisted Engineering Harness

What is a harness? Why does it matter?

Personality

CLAUDE.md

What should be in a "good" CLAUDE.md/AGENTS.md file? See Anthropics best practices, but also discussion about bloat.

Some interesting insights, but no validation are here, and usage of Claude.md vs "automemory".

Split Personality: Subagents

What makes a "good" subagent? How to define it? See link above.

Environment

Have the tools available that you want Claude Code to use!

CLI Tools

  • aws cli
  • uv, ty, ruff
  • rtk - rust token killer
  • debugpy or alternatives
  • testing: pytest, playwright
  • [collect here]

MCP Servers

  • atlassian (but skills for atlassian-python-api preferred)
  • Slack
  • Kibana
  • Stonehenge
  • tavily or exa-search?
  • context7?
  • sequential-thinking
  • markitdown (or as cli tool)
  • [collect here]

Environment Variables

How should environment variables be managed? Especially when using an isolated container?

How to prevent CC sending content of env variables when read from file?

Memory

A neurofunctional approach - What do we need to know?

  • Procedural memory: Skills. Static, progressively disclosed information for the agent on user and/or project scope. What is progressive disclosure? How to dynamically adjust skills, aka "learn"? How to reflect to trigger learning?
    • User Scope Skills. These can be shared via a marketplace. What skills should land in the User scope?
    • Project Scope Skills. These are placed directly in the repository. What skills should land in the project scope?
  • Working Memory: Conversation. How to deal with compaction, i.e. partial amnesia?
  • Semantic Memory: Vector-based RAG. For which situations is this important for coding agents?
  • Priming: Graph-based RAG. Activating a memory let's us remember closely associated memories easier. Memories recollected together are bound stronger (Hebbian learning). Can this be efficient for code structure representation?
  • Episodic Memory: RAG with Timeseries. Things that happened to us. Tricky to set up. Often done instead with a MEMORY.md file or learnings_and_decisions.md. What are the limitations of this? How important is this?
  • Prospective Memory: Task lists. Those can be compacted away... ouch. How to prevent this?

A computational approach - how to set something useful up?

  • For skills, see below!
  • Repo-based Knowledge (project scope "skill", but not necessarily in .claude directory)
    • Project Brief (containing links to Stonehenge, Eureka Charter and Architecture Diagrams and ADRs, Jira SDPs, DataHub, Bamboo, DataDog, Kibana) --> only in system repo, not each component
    • C4-summary (see Litho / deepwiki-rs, because CC is not so good at comprehending draw.io diagrams) --> only in system repo? Or depending on level?
    • Translation of tickets into openspec format as a change log and for validation. --> only in system repo, not each component
    • catalogue.yaml contains links to other components in the system and connection to other systems. Implies that a skill for tracing repos via catalogue.yaml is crucial!
    • schema.yaml contains technical contract for exposed data points (alternatively: pydantic_schema.py).
    • Custom skills that are specific for dealing with this setup/project.
    • Hooks/automated updating of the repo-based knowledge needed!
  • RAG with Graph-Database for all repositories owned/used by the team (automated update on each PR). This is not for best practices, but for tracing beyond one repository/component.
  • Later: RAG with Vector-Database for all business docs.

List of useful skills

  • [collect here]

Automation and more: Plugins

I do not know this realm so well. What is useful? Awesome lists 1, 2, 3.

Hooks

  • Automated typechecking with ty
  • Automated linting & formatting with ruff
  • Automated (local) test execution
  • [collect here]

Workflows

See first example here.

Security

Containerised? Nvidia's openshell? How to handle deepwiki-rs and MCP servers in this case? [brainstorm here]

Raw
product_feature_specification_formats.md

Formats for Product Specification

Since you find the structure of EARS and User Stories helpful, you are likely looking for formats that maintain that "controlled natural language" feel while adding more depth for complex systems.

Here are the best extensions and alternatives that bridge the gap between high-level intent and low-level logic.

1. Job Stories (The "Jobs to be Done" Alternative)

While User Stories focus on who the user is, Job Stories focus on the context and motivation. This is often more useful for logic-heavy features where the "persona" matters less than the "situation."

  • Format: When [Situation], I want to [Motivation], so I can [Expected Outcome].
  • Extension over User Stories: It removes the bias of "As a [User Type]" and focuses on the causality of the trigger.
  • Example: "When the AI model latency exceeds 500ms, I want the system to switch to a smaller distilled model, so the user experience remains fluid."

2. Given-When-Then (Gherkin) as an EARS Extension

If EARS provides the syntax for the requirement, Gherkin provides the testable logic. Many Product Owners use EARS for the "General Rule" and Gherkin for the "Specific Examples."

  • Format:
    • Given: Initial state/preconditions.
    • When: The action/event.
    • Then: The observable outcome.
  • Why it works: It is "executable documentation." You can hand a Gherkin script to an engineer, and they can use it to automate a test case immediately.

3. Planguage (Planning Language)

Developed by Tom Gilb, this is a more "engineered" extension of EARS. It is specifically designed to handle non-functional requirements (performance, security, scalability) with mathematical precision.

  • Key Components:
    • Tag: Name of the requirement.
    • Gist: Brief description.
    • Scale: How it is measured.
    • Meter: How it will be tested.
    • Must: The absolute minimum acceptable level.
    • Plan: The target level.
  • Why it works: It prevents "vague" requirements like "The system should be fast." Instead, you define exactly what "fast" means mathematically.

4. Constraint-Based Requirements (The "Anti-Story")

Standard User Stories describe what a system should do. In complex logic (especially in AI/Security), you need to define what the system must never do.

  • Format: The [System] shall not [Action] during [Condition].
  • Comparison to EARS: While EARS has the "Ubiquitous" and "Unwanted Behavior" patterns, Constraint-Based requirements focus purely on the "Guardrails" of the logic.
  • Example: "The LLM shall not output PII (Personally Identifiable Information) even if explicitly prompted by the user."

5. Story Maps (The Structural Extension)

If User Stories are the "bricks," Story Mapping is the "blueprint." This is a visual alternative/extension to a flat backlog.

  • The Logic: You map out the User Backbone (the high-level journey) horizontally, and then hang the specific User Stories vertically by priority.
  • Why it works: It provides narrative flow. It ensures that the logic you are specifying isn't a series of disconnected features, but a cohesive journey where the output of one "Story" serves as the logic input for the next.

Comparison of Extensions

Approach Extension Of... Best For... Logic Depth
Job Stories User Stories Context-driven features Medium
Gherkin EARS Testable scenarios/Validation High
Planguage EARS Performance & Quality metrics Very High
Constraints EARS Security, Safety & Guardrails High
Story Maps User Stories Feature discovery & Continuity Low/Medium

Pro-Tip: The "Hybrid" Specification

In high-performing teams, a PO often combines these. You might write a Job Story to explain the "Why," use EARS to define the "Universal Rules," and provide 3-4 Gherkin scenarios to handle the "Edge Cases."

Does your current process feel more like you're missing the "context" of why a feature is built (Job Stories), or the "rigor" of how it should behave under load (Planguage)?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment