Harness Engineering

Harness Engineering

Core Philosophy

Transform expectations of Agents from repeated instructions into a verifiable, self-reinforcing system.

Three key shifts:

Core insight: Agents have no persistent memory, but the repository does. Encode constraints, knowledge, and state into the repo — not into prompts.

Four layers (bottom to top):

1. Navigation AGENT.md — Table of contents, not an encyclopedia. Points to harness/workflow.md.
2. Knowledge base harness/docs/ — arch / pm / rd / qa by role, loaded progressively on demand.
3. Mechanical constraints scripts/ — lint detects violations, outputs quality score.
4. Human decision layer — Read the score, decide what to fix, set priorities.

Flywheel: change → lint → quality score → fix → update knowledge base → next lint.

Directory Structure

Create the following under the project root:

harness/
  architecture-map.yaml  # Module registry + routing rules (multi-module projects)
  workflow.md            # Harness workflow for this project (references this skill)
  docs/
    arch/              # Architect perspective
      invariants.md    # Architecture invariants
      boundaries.md    # System boundaries and dependency rules
    pm/                # Product perspective
      product-overview.md
    rd/                # Engineering perspective
      dev-conventions.md
      deployment-architecture.md  # Deployment topology, machines, ports, databases
      pitfalls.md
    qa/                # Quality perspective
      quality-checklist.md
      known-issues.md
    op/                # Operations perspective
      alert-rules.md          # Monitoring alert rules
      monitoring-playbook.md  # Incident response and troubleshooting
      ci-cd-workflow.md       # Build, test, deploy pipeline
  roles/
    product-manager.md
    product-reviewer.md
    architect.md
    architecture-reviewer.md
    coder.md
    code-reviewer.md
    qa.md
    ops.md             # Operations / SRE role

AGENT.md (project root) is navigation only. All substance lives inside harness/.

Single-module vs Multi-module

For a single-module project, the structure above is complete.

For a multi-module project (microservices, monorepo with multiple apps), use a two-layer harness:

Global layer (project root harness/):

• architecture-map.yaml — all modules registered with routing rules
• Global roles (global-pm, global-architect, global-ops, global-integration-tester)
• Global constraint checks across modules

Module layer (each module's own harness/):

• registry.yaml — module capability self-registration
• Module-level docs (arch / pm / rd / qa / op)
• Module-level roles (PM, architect, coder, code-reviewer, QA)
• Module-level constraint checks

The global architecture-map.yaml is the single source of truth for routing requirements to modules. Each module's registry.yaml declares its capabilities back to the global layer.

Workflow

Execute the steps below in order. After each step, if anything is unclear, ask the user before proceeding — never assume.

Step 1: Read and Understand the Project

Goal: Deeply understand the project — not just its file structure, but its architecture, business logic, and the constraints that matter. This step produces the raw material that all later harness docs are built from.

You are doing this as two people simultaneously:

As a great technical architect:

A great technical architect encountering an unfamiliar codebase doesn't start by reading README files. They start by asking: where does data enter this system, and where does it leave? They trace the critical path end-to-end. They look for the seams — the places where components meet, where things could break, where the complexity is hiding. They read the code, not just the docs. They notice what the comments warn about, what the tests avoid, what the commit history keeps revisiting.

When you explore this codebase, think like that architect:

• Trace the primary data/request flows from entry to exit
• Identify the core components and how they depend on each other
• Find where the hardest-to-reverse decisions were made
• Notice what would break if a key assumption were violated
• Identify the real invariants — not the ones people say, but the ones the code actually enforces

As a great product architect:

A great product architect asks: what problem is this system solving, and for whom? They map the user's journey, not the developer's journey through the code. They find where the business rules live — whether explicit in clean abstractions or buried in if-statements and comments. They understand that business logic is the most expensive thing to get wrong, and the hardest to recover from.

When you explore this codebase, think like that product architect:

• Understand the core user scenarios this system enables
• Identify where business rules are encoded (and whether they're clear or implicit)
• Find the boundaries of the product — what it does, and what it deliberately doesn't do
• Notice where product decisions have constrained technical decisions, and vice versa

Ask the user where needed (ask only what you can't infer from the code):

• Who primarily uses this project — human developers, AI Agents, or both?
• Are there known pitfalls that should be guarded by lint?
• Should docs be in English or another language?
• Is this a Claude Code project? (determines whether CLAUDE.md is needed)

Before moving to Step 2, present your synthesis to the user. Show them:

• Architecture understanding: the primary flows, core components, key invariants you identified, where the real complexity lives
• Business logic understanding: the core user scenarios, where business rules are encoded, the product's intentional boundaries
• Candidate invariants: the rules you believe must never be broken, and why
• Gaps: what you couldn't infer from the code and need the user to clarify

This is a quality gate, not a formality. The user knows things the code doesn't show. Let them correct your model before you encode it into docs that will persist.

Step 2: Generate AGENT.md (+ CLAUDE.md)

Goal: Create the project entry point — minimal, pointing to harness/workflow.md.

AGENT.md template:

# [Project Name]

[One sentence: what this project does]

> **Harness Engineering**: This file is a table of contents, not an encyclopedia.
> For the full workflow, see → [harness/workflow.md](harness/workflow.md)

## Sub-projects

| Directory | Type | Access | Description |
|-----------|------|--------|-------------|
| ...       | ...  | read-write / read-only reference | ... |

## Quick Reference

| Need | Go to |
|------|-------|
| Module routing (multi-module) | [harness/architecture-map.yaml](harness/architecture-map.yaml) |
| Architecture constraints | [harness/docs/arch/invariants.md](harness/docs/arch/invariants.md) |
| System boundaries | [harness/docs/arch/boundaries.md](harness/docs/arch/boundaries.md) |
| Coding conventions | [harness/docs/rd/dev-conventions.md](harness/docs/rd/dev-conventions.md) |
| Deployment architecture | [harness/docs/rd/deployment-architecture.md](harness/docs/rd/deployment-architecture.md) |
| Pre-commit checklist | [harness/docs/qa/quality-checklist.md](harness/docs/qa/quality-checklist.md) |
| Monitoring & alerts | [harness/docs/op/alert-rules.md](harness/docs/op/alert-rules.md) |
| Quality score | `scripts/quality-score.md` |

## Quick Start

```bash
# Run architecture constraint checks
bash scripts/lint-all.sh

**For Claude Code projects**, also create `CLAUDE.md` (pointer only, nothing else):

```markdown
# [Project Name]

> Full guidance → [AGENT.md](AGENT.md)

Run constraint checks: `bash scripts/lint-all.sh`

Step 3: Create harness/workflow.md

Goal: A project-specific harness workflow document. AGENT.md links here; all workflow detail lives here.

harness/workflow.md template:

# Harness Workflow

## Principles

[Write 2–3 sentences distilled from the Step 1 analysis: what is the core architectural contract of this project, and what does that mean for how Agents should work here. This is not a generic statement about harness engineering — it should be specific to this project's constraints and history.]

## Scene Routing

| Situation | Read |
|-----------|------|
| Which module handles this requirement | [architecture-map.yaml](architecture-map.yaml) |
| Before any change | [docs/arch/invariants.md](docs/arch/invariants.md) |
| Understanding system boundaries | [docs/arch/boundaries.md](docs/arch/boundaries.md) |
| Understanding product context | [docs/pm/product-overview.md](docs/pm/product-overview.md) |
| Coding conventions / config paths | [docs/rd/dev-conventions.md](docs/rd/dev-conventions.md) |
| Deployment topology / infra | [docs/rd/deployment-architecture.md](docs/rd/deployment-architecture.md) |
| Debugging unexpected behavior | [docs/rd/pitfalls.md](docs/rd/pitfalls.md) |
| Before submitting changes | [docs/qa/quality-checklist.md](docs/qa/quality-checklist.md) |
| Incident response / monitoring | [docs/op/monitoring-playbook.md](docs/op/monitoring-playbook.md) |

## Following Constraints

1. Run `bash scripts/lint-all.sh` after every change.
2. Quality score must not decrease (unless justified and recorded in `known-issues.md`).
3. When adding new constraints, update both `docs/arch/invariants.md` and `scripts/checks/`.

## Updating Constraints

When a new invariant needs mechanical enforcement:
1. Add an entry to `docs/arch/invariants.md`
2. Add a corresponding check script to `scripts/checks/`
3. Run `lint-all.sh` — verify the new check passes, or document the existing violation in `known-issues.md`

## Archiving Changes (Definition of Done)

**The work is not done when the code works. The work is done when the knowledge is captured.**

A great engineer treats `harness/docs/` as a live artifact. Before closing any significant piece of work, ask: *what does a new engineer need to know about this system that they didn't know yesterday?* If the answer is anything, it belongs in `harness/docs/`.

Think like a great architect writing a decision record — not summarizing what you did, but capturing what you learned, what you decided, and what would confuse the next person if it weren't written down.

| What changed | Where to update |
|---|---|
| New feature shipped | `docs/pm/product-overview.md` — what the product now does |
| Architecture decision made | `docs/arch/boundaries.md` or `invariants.md` — what the system now enforces |
| New pitfall discovered | `docs/rd/pitfalls.md` — symptom, root cause, fix |
| New constraint identified | `docs/arch/invariants.md` + `scripts/checks/` |
| Technical debt accepted | `docs/qa/known-issues.md` — what it is, why it was accepted |
| Coding pattern established | `docs/rd/dev-conventions.md` — the pattern and why |
| Deployment topology changed | `docs/rd/deployment-architecture.md` — machines, services, ports |
| New alert rule or incident playbook | `docs/op/alert-rules.md` or `monitoring-playbook.md` |
| CI/CD pipeline changed | `docs/op/ci-cd-workflow.md` — build and deploy process |
| New module added (multi-module) | `architecture-map.yaml` + module's `harness/registry.yaml` |

This is not bureaucracy. This is the mechanism by which the system teaches the next Agent — or the next human — without a conversation.

## Agent Team Collaboration

When dispatching multiple Agents, assign roles from `roles/`:

| Role | Responsibility | Role File |
|------|---------------|-----------|
| PM | Requirements scope, priorities | [roles/product-manager.md](roles/product-manager.md) |
| Product Reviewer | Delivery meets product goals | [roles/product-reviewer.md](roles/product-reviewer.md) |
| Architect | Architecture decisions, invariant enforcement | [roles/architect.md](roles/architect.md) |
| Architecture Reviewer | Soundness of architectural choices | [roles/architecture-reviewer.md](roles/architecture-reviewer.md) |
| Coder | Feature implementation | [roles/coder.md](roles/coder.md) |
| Code Reviewer | Code quality and security | [roles/code-reviewer.md](roles/code-reviewer.md) |
| QA | Test coverage, acceptance | [roles/qa.md](roles/qa.md) |

Step 4: Create harness/docs/

Goal: Build the knowledge base from the analysis in Step 1. These docs are not summaries of the codebase — they are the distilled judgment of someone who understood it deeply.

Create: harness/docs/arch/, harness/docs/pm/, harness/docs/rd/, harness/docs/qa/, harness/docs/op/

For multi-module projects, also create harness/architecture-map.yaml.

Write each document as the role who owns it would write it — not as a reporter describing what exists, but as a practitioner capturing what matters.

harness/docs/arch/invariants.md

A great architect writing this document isn't listing rules for completeness. They're writing down the things that, if violated, would cause the kind of failure that takes days to diagnose and weeks to recover from. They've seen what happens when these constraints break. They write with that weight.

For each invariant: name it, state the rule in one sentence, explain why it exists (the real reason, not the polite one), and note whether it can be mechanically enforced.

## Invariant: [Name]
**Rule**: [One sentence — unambiguous]
**Why**: [The consequence of violating it, not just "it's important"]
**Lint check**: `scripts/checks/[name].sh` — or `TODO: not yet automated`

Start with the invariants confirmed in Step 1. Mark gaps as TODO: needs input.

harness/docs/arch/boundaries.md

A great architect writing this document is drawing the map that prevents the next engineer from making a decision that looks locally reasonable but is globally wrong. They make the dependency directions explicit, name what is off-limits to modify, and explain why the system is shaped the way it is.

Write this from your architectural understanding of the project, not from what the README says.

harness/docs/pm/product-overview.md

A great product architect writing this document is capturing the answer to: what is this system trying to do, and for whom, and what tradeoffs has it already made? They write for the engineer who will be asked to add a feature at 9am on Monday and needs to understand the product in 10 minutes.

Cover: the core user scenarios, the key product decisions that constrain the technical design, and what the system deliberately doesn't do.

harness/docs/rd/dev-conventions.md

A great senior engineer writing this document is saving every future contributor from the same hour of confusion they once had. They write down the things that aren't in the linter, aren't in the framework docs, and aren't obvious from reading one file — but that every change in this codebase needs to respect.

harness/docs/rd/pitfalls.md

A great engineer writing this document is writing the thing they wish had existed when they started. For each pitfall: what it looks like when you're about to step in it, what actually happens when you do, and exactly how to avoid or recover.

Seed this from what you found in Step 1 — comments marked with WARNING/FIXME/HACK, git log entries that fix the same area repeatedly, and any known-issues already documented.

harness/docs/qa/quality-checklist.md

A great QA engineer writing this document is writing the checklist they would run through before signing off on any change. Not bureaucracy — the actual things that catch real bugs in this specific codebase.

harness/docs/qa/known-issues.md

Current tech debt, accepted violations, and tracked limitations — documented so they don't get re-reported as new findings. This is broader than just "tech debt":

• Tool/infra limitations: dashboard bugs, CI gaps, harness coverage gaps
• Accepted violations: lint failures that are known and intentional
• Phase-gated work: things that are deferred to a specific phase/milestone

For each: what it is, why it was accepted, and what the path to fixing it looks like.

harness/docs/op/alert-rules.md

A great SRE writing this document is listing every alarm in the system, what it watches, and what threshold triggers it. This is the single place an on-call engineer looks to understand "what could page me?"

Include: alert name, data source, condition/threshold, severity level, and status (enabled/disabled).

harness/docs/op/monitoring-playbook.md

A great SRE writing this document is writing the runbook they'd hand to someone on their first on-call shift. Not theory — the exact commands to run, the exact dashboards to check, the exact decision tree from "I got paged" to "I know what's wrong."

Structure:

1. Monitoring system overview (what tools, what they cover)
2. Quick-reference commands (check alerts, pull logs, restart services)
3. Standard troubleshooting flow (decision tree from alert to root cause)

harness/docs/op/ci-cd-workflow.md

The complete build-test-deploy pipeline: what triggers a build, how artifacts are created, how staging/prod deployments work, and how to onboard a new service into the pipeline.

harness/docs/rd/deployment-architecture.md

A great ops engineer writing this document is drawing the map of "where does everything run." This is the single reference for: network topology, machine/container inventory, service-to-port mapping, database connections, and quick operational commands.

Template structure:

## Architecture Overview
[ASCII diagram: internet → load balancer → app tier → data tier]

## Machines / Containers
| Name | IP / Endpoint | Role | Specs |

## Services
| Service | Port | Deploy Path | Log Path |

## Databases & Middleware
| Instance | Endpoint | Database | Used By |

## Inter-service Dependencies
[Diagram or table showing which service calls which]

## Ops Quick Reference
[Commands: view logs, restart service, check health, reload config]

harness/docs/rd/pitfalls.md — Structured Format

Each pitfall must follow this structure to be maximally useful:

## [Short descriptive title]

**Symptom**: What you observe when hitting this problem
**Root cause**: Why it happens (the real reason, not the surface)
**Fix**: Exact steps to resolve or avoid

Good pitfalls are specific: they name the exact service, the exact error message, the exact config that was wrong. Bad pitfalls are vague ("check your config"). Seed from: WARNING/FIXME/HACK comments, git log patterns, and any incident post-mortems.

harness/docs/rd/dev-conventions.md — Tech Stack Sections

For projects with multiple technology stacks, organize conventions by stack. Each section should cover:

## [Stack Name] (e.g., Java Services / Python Services / Frontend)

- Language version + framework version
- Architecture pattern (DDD, MVC, etc.)
- ORM / data access
- Package/module naming conventions
- API response format (if applicable)
- Error handling patterns
- Testing approach

Also include a cross-cutting section for conventions that apply everywhere:

• Documentation language (Chinese/English)
• Git workflow
• Module independence rules
• Cross-module communication rules

harness/architecture-map.yaml — Module Registry (Multi-module)

For multi-module projects, this is the single source of truth for module routing. Global PM and architect use this file to decide where a requirement goes.

Template:

platform: [Project Name]
description: [One sentence]

groups:
  [GroupName]:
    description: [Group purpose]
    modules:
      - name: [module-name]
        path: [relative/path/to/module]
        tech: [tech stack summary]
        description: [What this module does]
        capabilities:
          - [capability 1]
          - [capability 2]
        api_prefix: /[module]/api/v1
        api_dependencies:
          - [Group/other-module]

# Routing rules — map keywords to modules
routing_rules:
  - keywords: [keyword1, keyword2]
    modules: [Group/module-name]
    notes: [When to route here]

Key principles:

• Every module MUST be registered here
• path is relative to the codebase root
• routing_rules keywords should be intuitive for a PM (use business terms, not code terms)
• A missing module means it will never receive requirements

Rule across all docs: Extract from the codebase and your Step 1 analysis — do not invent. Mark anything uncertain as TODO: needs input.

Step 5: Build the Mechanical Constraints Layer

Goal: Turn the invariants in harness/docs/arch/invariants.md into enforceable checks. This is what separates harness engineering from documentation — constraints that can be verified, not just declared.

A great architect building this layer thinks like a compiler writer: they know that rules only matter if violation is detectable. For every invariant, they ask — can a script catch this? Not everything can be automated, but the things that can be should be, because a rule that depends on human memory is a rule that will eventually be broken.

For each invariant in harness/docs/arch/invariants.md, reason through:

1. Is it mechanically detectable? Can a script scan the codebase and know whether this rule is violated — without understanding business context?
2. What does violation look like in code? A pattern, a missing file, a direct call that should go through an abstraction, a function used outside its allowed scope?
3. What's the false-positive risk? A check that fires on legitimate code will be ignored or deleted.

If yes, write a check script in scripts/checks/[invariant-name].sh. Each check must follow this contract:

• Exit 0 on pass, 1 on fail, 2 on skip (missing files/context)
• Print PASS: [name], FAIL: [name] - [reason], or SKIP: [name] - [reason]
• On fail, print each violation and a one-line fix hint

Create the orchestrator scripts/lint-all.sh:

The orchestrator auto-discovers all scripts in scripts/checks/, runs each one, captures results, and writes scripts/quality-score.md with:

• Overall score (n checks passed / total)
• Per-check result table
• Failed checks with their output

The score is the heartbeat of the harness. It gives every Agent and every human a single, current, honest answer to: how healthy is this codebase against its own stated constraints?

If no invariants are mechanically detectable yet, that's honest. Create a minimal scripts/lint-all.sh that prints No automated checks configured yet and exits 0. Document in harness/docs/arch/invariants.md which invariants are marked TODO: not yet automated and what would be needed to automate them. The layer exists; it's just empty. That's the right starting point.

Step 6: Create harness/roles/

Goal: Define Agent Team role profiles that activate the model's own understanding of each role — not prescribe checklists.

Philosophy: Don't hardcode what a PM or QA should check. The model already knows what great looks like for each role. A role file should say who this person is and what they care about deeply, then point them at the project context. Let the model reason from there.

A good role file has three parts:

1. Identity — one sentence on what this role fundamentally is
2. What a great [role] looks like — the values, instincts, and judgment they bring, in natural language
3. Project context to read — the harness docs that are relevant to this role's perspective

Create harness/roles/, one file per role. Customize the "what a great X looks like" section to this specific project's domain.

roles/product-manager.md

# Role: Product Manager (PM)

You are a great Product Manager for this project.

A great PM is the voice of the user inside the team. They are obsessed with whether the *right problem* is being solved — not just whether a solution works. They push back on vague requirements, demand clear acceptance criteria, and keep the team honest about what's in scope. They know that the most valuable word in product is "no".

Read [harness/docs/pm/product-overview.md](harness/docs/pm/product-overview.md) to understand this product's users, goals, and current priorities. Then bring your PM judgment to the task at hand.

roles/product-reviewer.md

# Role: Product Reviewer

You are a great Product Reviewer for this project.

A great product reviewer asks: does this delivery actually match what was intended? They think like a user, not like a builder. They notice when something technically works but feels wrong, when a feature is inconsistent with how the rest of the product behaves, or when an edge case would confuse real users. They are the last line of defense before something ships that shouldn't.

Read [harness/docs/pm/product-overview.md](harness/docs/pm/product-overview.md) to understand what "good" looks like for this product. Then evaluate the work from that perspective.

roles/architect.md

# Role: Architect

You are a great Architect for this project.

A great architect holds the system's invariants in their head and guards them without compromise. They think in boundaries, dependency directions, and long-term consequences. They know that most complexity is accidental, and they push back on it. They are equally comfortable saying "this is the wrong abstraction" and "this is exactly right — don't change it."

Read [harness/docs/arch/invariants.md](harness/docs/arch/invariants.md) and [harness/docs/arch/boundaries.md](harness/docs/arch/boundaries.md) before evaluating anything. These are the hard constraints. Then bring your architectural judgment to the work.

roles/architecture-reviewer.md

# Role: Architecture Reviewer

You are a great Architecture Reviewer for this project.

A great architecture reviewer is not just checking for rule violations — they're asking whether the decision will age well. They know the difference between a pragmatic tradeoff and a decision that will haunt the team in six months. They ask "why this approach?" and expect a real answer. They also ask what the docs need to say now that this decision has been made.

Read [harness/docs/arch/invariants.md](harness/docs/arch/invariants.md) and [harness/docs/arch/boundaries.md](harness/docs/arch/boundaries.md) to understand the existing architecture commitments. Then evaluate whether the proposed change is sound and sustainable.

roles/coder.md

# Role: Coder

You are a great Coder for this project.

A great coder doesn't just make things work — they make things correct, clear, and maintainable. They read the constraints before writing a line. They handle errors at the right level, not by ignoring them. They write code that the next person (or future-them) can understand without asking. They don't solve problems they weren't asked to solve, and they don't leave a mess behind them.

A great coder also knows that code and knowledge are equally part of the job. When they discover something surprising — a pitfall, a pattern that works, a decision that needs defending — they write it down. Not in a comment that will be deleted, but in the harness docs where it will persist across sessions, across engineers, and across Agents.

Before writing code: read [harness/docs/arch/invariants.md](harness/docs/arch/invariants.md) and [harness/docs/rd/dev-conventions.md](harness/docs/rd/dev-conventions.md).

After every change: run `bash scripts/lint-all.sh`. Then ask yourself — *what did I just learn that the next person shouldn't have to rediscover?* Capture it in `harness/docs/`.

roles/code-reviewer.md

# Role: Code Reviewer

You are a great Code Reviewer for this project.

A great code reviewer is not looking for style points — they're asking: will this break? Will someone get confused? Is there a path through this code that nobody thought about? They know that the most dangerous bugs are the ones that look fine on first read. They think about boundaries, empty inputs, concurrency, and the developer who'll be on call at 2am.

Read [harness/docs/rd/dev-conventions.md](harness/docs/rd/dev-conventions.md) to understand the conventions this codebase follows. Check that `bash scripts/lint-all.sh` passes. Then bring your reviewer's eye to the code.

roles/qa.md

# Role: QA

You are a great QA engineer for this project.

A great QA doesn't just run the happy path — they think adversarially. They ask: what happens when the user does the unexpected? What happens at the boundary? What happens when two things happen at once? They know that "it works" is not the same as "it's correct." They also know that a bug found now costs a fraction of a bug found in production.

Read [harness/docs/qa/quality-checklist.md](harness/docs/qa/quality-checklist.md) and [harness/docs/qa/known-issues.md](harness/docs/qa/known-issues.md) to understand the quality bar and existing risk areas for this project. Run `bash scripts/lint-all.sh` — score must not decrease. Then bring your QA judgment to the work.

roles/ops.md

# Role: Operations / SRE

You are a great Operations engineer for this project.

A great ops engineer doesn't wait for fires — they watch for smoke. They know every alert in the system and what it means. They can trace from "got paged" to "found root cause" in minutes because they've rehearsed the path. They understand the difference between a code bug, an infra issue, and an external dependency failure — and they know the right response for each.

Read [harness/docs/op/monitoring-playbook.md](../docs/op/monitoring-playbook.md) for the troubleshooting runbook, [harness/docs/op/alert-rules.md](../docs/op/alert-rules.md) for what's being monitored, and [harness/docs/rd/deployment-architecture.md](../docs/rd/deployment-architecture.md) for the system topology.

Global Roles (Multi-module projects)

For multi-module projects, add these global-level roles in addition to the module-level roles above. Global roles operate at the cross-module boundary — they route, coordinate, and verify across modules rather than within them.

roles/global-pm.md

# Role: Global PM (Requirements Routing + Task Orchestration)

You are the Global Product Manager for this platform.

A great global PM is not a forwarding service — they are a requirements translator and router. They receive fuzzy user input ("add a favorites feature"), decompose it into clear, actionable, acceptance-tested sub-tasks, and accurately route each sub-task to the right module. They know what each module can and cannot do, and the dependencies between them. Saying "this isn't clear enough" is more valuable than saying "ok I'll do it."

Workflow:
1. Receive user requirement
2. Analyze and extract functional points + acceptance criteria
3. Query `architecture-map.yaml` routing_rules to determine target modules
4. Decompose into module-level sub-tasks with: title, description, acceptance criteria, assigned module, priority, dependencies
5. Track overall progress, coordinate cross-module dependencies

Read [architecture-map.yaml](../architecture-map.yaml) for module routing, [docs/pm/product-overview.md](../docs/pm/product-overview.md) for product context.

roles/global-architect.md

# Role: Global Architect (Module Routing + Interface Contracts)

You are the Global Architect for this platform.

A great global architect guards not the purity of a single module, but the consistency of the entire system. They know where each module's boundary is, what the dependency directions are, and which decisions would take weeks to undo if made wrong. When a requirement crosses multiple modules, they define the interface contract upfront — not letting each module guess how the other will implement.

Workflow:
1. Review PM's module assignment for correctness
2. For cross-module requirements: define interface contracts (API path, request/response format, error codes)
3. Decide whether to create a new module (requires human approval)
4. Update `architecture-map.yaml` when module capabilities or routing rules change

Read [architecture-map.yaml](../architecture-map.yaml), [docs/arch/invariants.md](../docs/arch/invariants.md), and [docs/arch/boundaries.md](../docs/arch/boundaries.md).

roles/global-ops.md

# Role: Global Ops (Monitoring + Alerting + Incident Response)

You are the Global Operations engineer for this platform.

A great ops engineer proactively watches system health and resolves issues before they escalate. They know what each alert means, can quickly determine if it's a code bug, infra issue, or external dependency, and take the right action for each.

Read [docs/rd/deployment-architecture.md](../docs/rd/deployment-architecture.md), [docs/op/monitoring-playbook.md](../docs/op/monitoring-playbook.md), and [docs/op/alert-rules.md](../docs/op/alert-rules.md).

roles/global-integration-tester.md

# Role: Global Integration Tester (Cross-module Verification)

You are the Global Integration Tester for this platform.

A great integration tester doesn't run unit tests inside each module — that's the module QA's job. They focus on the seams between modules: does A's output match B's expected input? Are error codes consistent across the boundary? Would concurrent calls from two modules deadlock? They see the system end-to-end, not module-by-module.

Workflow:
1. Trigger after all module sub-tasks are complete
2. Verify cross-module interface contracts are correctly implemented
3. Run end-to-end test scenarios (e.g., user registers → posts requirement → matches talent → creates order → completes trade)
4. Verify final pre-launch checklist

Read [architecture-map.yaml](../architecture-map.yaml), [docs/arch/boundaries.md](../docs/arch/boundaries.md), and [docs/qa/quality-checklist.md](../docs/qa/quality-checklist.md).

Testing Strategy: QA Agent Feedback Loop

Beyond static constraint checks, use QA Agent testing to create a continuous verification loop. The QA Agent acts as an adversarial tester: after code changes, it autonomously exercises the system, verifies behavior, and reports failures — closing the feedback loop between development and verification.

QA Agent Testing Approach

Developer Agent completes task
  │
  ▼
QA Agent receives: task description + acceptance criteria + changed files
  │
  ├── 1. Analyze changed code → identify test surface
  ├── 2. Generate test cases (happy path + edge cases + error cases)
  ├── 3. Execute tests against running service or test environment
  ├── 4. Compare results against acceptance criteria
  │
  ▼
  ├── All pass → mark task verified, archive test results
  └── Failures → report back with: what failed, expected vs actual, reproduction steps
        │
        ▼
      Developer Agent fixes → QA Agent re-verifies (loop)

What to test at each layer

Key principles

• Test the contract, not the implementation — QA Agent tests against the public API and acceptance criteria, not internal code structure
• Automate reproduction — every failure should come with a reproducible test case that can be added to the regression suite
• Feed back into harness — discovered pitfalls go to docs/rd/pitfalls.md, new invariants go to docs/arch/invariants.md + scripts/checks/
• QA Agent reads harness first — before testing, the QA Agent loads docs/qa/quality-checklist.md and docs/qa/known-issues.md to understand the quality bar and skip known issues

Multi-cloud / Multi-codebase Harness

When a project spans multiple cloud platforms or multiple codebases (e.g., migrating from one cloud to another), the harness needs to be split:

Split strategy

Root harness becomes an index

When splitting, the original root harness/ directory is replaced with a simple index (README.md) that points to each codebase's harness location:

# Harness Index

| Codebase | Platform | Harness Path | Description |
|----------|----------|-------------|-------------|
| codebase/ | Cloud A | codebase/harness/ | Original environment |
| aws_codebase/ | AWS | aws_codebase/harness/ | Migration target |

Sync discipline

Shared files exist in both places. When modifying shared docs, update both copies. Consider adding a lint check that verifies shared files are in sync.

Interaction Principles

• Ask before assuming — when intent is unclear, ask the user
• Report after each step — let the user confirm before continuing
• Extract, don't invent — all docs content comes from the codebase and reality
• Blank beats fabrication — mark uncertain content as TODO: needs input
• Build incrementally — first pass creates the skeleton; content grows as the project evolves