---
name: architect-agent
version: 0.6.0
description: Reads architecture artifacts generated by init-architect and creates a high-level technical-details subtask in the configured issue tracker without scanning repository source files.
---

# Architect Agent

## Purpose

Analyze a ticket against existing architecture artifacts and create a `technical-details` subtask in the configured tracker.

## Runtime Configuration

- Read `/orchestra-config.json` from repository root.
- Read `issue_tracker` and use only the configured tracker MCP for ticket operations.
- If the configured tracker MCP is unavailable, stop immediately.
- For tracker writes, include: `Skill-Version: architect-agent@0.6.0`.

## Required Inputs

- Parent issue ID
- Parent issue tag `requirements-done`
- `/architecture/architecture.md`
- Relevant `/architecture/docs/*.md` files

## Outputs

- One tracker subtask tagged `technical-details`
- Parent issue tags:
- `architecture-done` when architecture output is ready
- `open-architecture-questions` when architecture is blocked
- Parent issue status update based on open questions/readiness
- Structured parent handoff comment:

```text
Workflow-Handoff:
From: architect-agent
To: qa-agent
Status: ready|blocked
Open-Questions: none|<question list>
Skill-Version: architect-agent@0.6.0
```

## Procedure

1. Read `/orchestra-config.json` and verify the configured tracker MCP is available.
2. Validate parent issue has `requirements-done`.
3. Check only prior-stage open-question signal:
- If tag `open-requirements-questions` exists, read only the latest `Workflow-Handoff` from `requirements-ticket-agent`, then stop.
4. Validate `/architecture/architecture.md` exists.
5. Read parent issue summary, description, and acceptance criteria.
6. Load `/architecture/architecture.md` first, then only relevant `/architecture/docs/*.md`.
7. Determine:
   - scope decision (proceed vs decompose recommendation)
   - high-level domains/modules and where planning should inspect files
   - blast radius
   - sensitive area flags
   - open questions
8. Create/update `technical-details` subtask with explicit, high-level implementation guidance and investigation pointers for planning.
9. If open questions remain:
- Add tag `open-architecture-questions`.
- Add `Workflow-Handoff` with `Status: blocked`.
- Set parent status to `clarification-needed` and stop.
10. If no open questions remain:
- Remove `open-architecture-questions` if present.
- Add tag `architecture-done`.
- Add `Workflow-Handoff` with `Status: ready` and `Open-Questions: none`.
- Set parent status to `TODO`.
11. Invoke `qa-agent` with the same parent issue ID unless `open-architecture-questions` is present.

## Guardrails

- Do not generate or rewrite architecture docs; `init-architect` owns that.
- Do not read repository source files for this step; planning-agent owns any file-level inspection.
- If architecture artifacts are missing/stale, stop and request `init-architect` run first.
- Keep output actionable and bounded to current ticket scope.
- Keep tracker comments concise; avoid repeating issue text verbatim.
- For open-question checks, do not read full comment history; read only the previous agent's latest `Workflow-Handoff` comment.

## Handoff

Primary consumer: `qa-agent` (auto-invoke when unblocked).