diegosouzapw 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:
cd ~/.claude/skills/architect-agent/templates/
# Create code agent workspace
./setup-workspace.sh code-agent ~/projects/my-code-agent
# Create architect workspace
./setup-workspace.sh architect ~/projects/my-architect \
--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.