Architect Agent Workflow Skill
Coordinate planning, delegation, and evaluation across architect and code agent workspaces.
Quick Start: Say "write instructions for code agent", "initialize workspace", "grade work", or "send instructions". For automated setup, see Quick Setup.
Table of Contents
- Intent Classification
- Decision Tree
- Resource Loading Policy
- Critical Protocol: File Locations
- Quick Setup
- DO NOT Trigger For
- Reference Directory
- Guides Directory
Intent Classification
Route requests based on user intent:
| Intent | Trigger Phrases | Action |
|---|---|---|
| Create Instructions | "write instructions", "create instructions", "delegate to code agent" | → Load guides/workflows/create-instructions.md |
| Initialize Workspace | "set up architect agent", "initialize workspace", "new architect agent" | → Load guides/workflows/initialize-workspace.md |
| Grade Work | "grade the work", "evaluate completed work", "review implementation" | → Load guides/workflows/grade-work.md |
| Send Instructions | "send instructions", "send to code agent" | → Load guides/workflows/send-instructions.md |
| Add OpenCode Support | "migrate to OpenCode", "add OpenCode support" | → Load references/opencode_integration_quickstart.md |
| Verify Setup | "verify setup", "test hooks", "check logging" | → Load references/workspace_verification_protocol.md |
| Setup Permissions | "set up permissions", "fix permission prompts" | → Load references/permissions_setup_protocol.md |
| Upgrade Workspace | "upgrade workspace", "migrate to v3.0" | → Load references/upgrade.md |
Decision Tree
| User Intent | Pre-condition | Action |
|---|---|---|
| "write/create instructions", "delegate" | instructions/ exists | Load guides/workflows/create-instructions.md |
| "write/create instructions", "delegate" | instructions/ missing | Suggest workspace initialization first |
| "set up/initialize" workspace | Directories don't exist | Load guides/workflows/initialize-workspace.md |
| "set up/initialize" workspace | Directories exist | Warn: already initialized |
| "grade", "evaluate" work | grades/ exists | Load guides/workflows/grade-work.md |
| "grade", "evaluate" work | grades/ missing | Suggest workspace initialization first |
| "send instructions" | — | Load guides/workflows/send-instructions.md (bash copy, no agents) |
| "verify", "test hooks" | — | Load references/workspace_verification_protocol.md |
| "OpenCode", "dual-mode" | — | Load references/opencode_integration_quickstart.md |
| "permissions" | — | Load references/permissions_setup_protocol.md |
| "upgrade", "migrate" | — | Load references/upgrade.md |
Resource Loading Policy
Load ONLY when needed:
- Workflow guides: When intent is classified
- Reference docs: When user needs detailed protocol
- Templates: When creating workspace or files
- Never load all references "just in case"
Core Resources by Intent:
| Intent | Primary Resource | Supporting Resources |
|---|---|---|
| Create Instructions | guides/workflows/create-instructions.md | references/instruction_structure.md, references/human_instruction_structure.md, references/file_naming.md |
| Initialize Workspace | guides/workflows/initialize-workspace.md | references/workspace_setup_complete.md |
| Grade Work | guides/workflows/grade-work.md | references/grading_rubrics.md, references/decision_types.md |
| Send Instructions | guides/workflows/send-instructions.md | (none - simple bash copy) |
| Verify Setup | references/workspace_verification_protocol.md | references/pre_work_checklist.md |
| Setup Permissions | references/permissions_setup_protocol.md | - |
| OpenCode Support | references/opencode_integration_quickstart.md | references/opencode_setup_guide.md |
Critical Protocol: File Locations
The architect agent operates in its own workspace, NOT the code agent workspace.
| Artifact | Architect Writes To | Code Agent Location |
|---|---|---|
| Instructions | [ARCHITECT]/instructions/ | Reads from debugging/instructions/ |
| Human Instructions | [ARCHITECT]/human/ | N/A (for manual execution) |
| Grades | [ARCHITECT]/grades/ | N/A |
| Logs | N/A | Writes to [CODE_AGENT]/debugging/logs/ |
Human Instructions = Executable Documentation (not summaries!)
Human instructions must enable manual execution when code agents are unavailable. Include copy-pasteable commands, expected output, and troubleshooting. See references/human_instruction_structure.md.
Guard Rail: If about to write to the code agent's workspace, stop and verify the operation.
Quick Setup (Template-Based)
For fastest setup, use templates:
bash1cd ~/.claude/skills/architect-agent/templates/ 2 3# Create code agent workspace 4./setup-workspace.sh code-agent ~/projects/my-code-agent 5 6# Create architect workspace 7./setup-workspace.sh architect ~/projects/my-architect \ 8 --code-agent-path ~/projects/my-code-agent
Time: <5 minutes
See: templates/README.md
DO NOT Trigger For
- General architecture discussions
- Brainstorming or exploration
- Reading/analyzing existing code
- Research tasks
- Any work that isn't explicit instruction creation, grading, or setup
Reference Directory
All detailed protocols are in references/. Load only what is needed for the current task.
Core References (Instruction & Grading)
| Reference | Purpose |
|---|---|
instruction_structure.md | Code agent instruction template |
human_instruction_structure.md | Human-executable instruction template |
grading_rubrics.md | 6-category grading criteria |
instruction_grading_workflow.md | Full grading workflow |
decision_types.md | decision, rationale, investigation, verification, deviation, milestone |
file_naming.md | Timestamp and naming conventions |
Setup & Configuration
| Reference | Purpose |
|---|---|
installation.md | Skill installation guide |
quick_start.md | Fast-track setup |
workspace_setup_complete.md | Full workspace initialization |
workspace_verification_protocol.md | Verify setup is correct |
permissions_setup_protocol.md | Cross-workspace permissions |
upgrade.md | Upgrade to latest version |
Logging & Debugging
| Reference | Purpose |
|---|---|
logging_protocol.md | Hybrid logging v2.0 |
hybrid_logging_protocol.md | Detailed hybrid logging spec |
hook_configuration_critical.md | Hook setup requirements |
hook_logger_enhancements.md | Hook logger improvements |
pre_work_checklist.md | Code agent pre-work verification |
get_unstuck_protocol.md | Recovery from blockers |
resilience_protocol.md | Error recovery patterns |
testing_protocol.md | Progressive testing requirements |
OpenCode Integration
| Reference | Purpose |
|---|---|
opencode_integration_quickstart.md | Dual-mode quick start |
opencode_setup_guide.md | Full OpenCode setup |
opencode_migration_guide.md | Migrate to OpenCode |
opencode_logging_protocol.md | OpenCode-specific logging |
opencode_wrapper_setup.md | Wrapper script setup |
claude_vs_opencode_comparison.md | Feature comparison |
Agent Configuration
| Reference | Purpose |
|---|---|
agent_specialization.md | Agent role configuration |
code_agent_claude_template.md | CLAUDE.md template for code agents |
code_agent_agents_template.md | AGENTS.md template for code agents |
Project Management
| Reference | Purpose |
|---|---|
git_pr_management.md | Git and PR workflow |
ticket_tracking_pr_management.md | Ticket and PR tracking |
Guides Directory
Step-by-step workflows in guides/workflows/:
| Guide | Trigger |
|---|---|
create-instructions.md | "write instructions for code agent" |
grade-work.md | "grade the code agent's work" |
send-instructions.md | "send instructions to code agent" |
initialize-workspace.md | "set up architect agent workspace" |
Templates
Ready-to-use workspace templates in templates/:
| Template | Purpose |
|---|---|
setup-workspace.sh | Automated workspace creation script |
architect-workspace/ | Complete architect agent workspace template |
code-agent-workspace/ | Complete code agent workspace template |
See: templates/README.md for usage instructions.
