SKILL.md
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](#quick-setup-template-based).
Table of Contents
- [Intent Classification](#intent-classification)
- [Decision Tree](#decision-tree)
- [Resource Loading Policy](#resource-loading-policy)
- [Critical Protocol: File Locations](#critical-protocol-file-locations)
- [Quick Setup](#quick-setup-template-based)
- [DO NOT Trigger For](#do-not-trigger-for)
- [Reference Directory](#reference-directory)
- [Guides 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/opencodeintegrationquickstart.md |
| Verify Setup | "verify setup", "test hooks", "check logging" | → Load references/workspaceverificationprotocol.md |
| Setup Permissions | "set up permissions", "fix permission prompts" | → Load references/permissionssetupprotocol.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/workspaceverificationprotocol.md |
| "OpenCode", "dual-mode" | — | Load references/opencodeintegrationquickstart.md |
| "permissions" | — | Load references/permissionssetupprotocol.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/instructionstructure.md, references/humaninstructionstructure.md, references/filenaming.md |
| Initialize Workspace | guides/workflows/initialize-workspace.md |
references/workspacesetupcomplete.md |
| Grade Work | guides/workflows/grade-work.md |
references/gradingrubrics.md, references/decisiontypes.md |
| Send Instructions | guides/workflows/send-instructions.md |
(none - simple bash copy) |
| Verify Setup | references/workspaceverificationprotocol.md |
references/preworkchecklist.md |
| Setup Permissions | references/permissionssetupprotocol.md |
- |
| OpenCode Support | references/opencodeintegrationquickstart.md |
references/opencodesetupguide.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/humaninstructionstructure.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-agentTime: <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 |
humaninstructionstructure.md |
Human-executable instruction template |
grading_rubrics.md |
6-category grading criteria |
instructiongradingworkflow.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 |
workspacesetupcomplete.md |
Full workspace initialization |
workspaceverificationprotocol.md |
Verify setup is correct |
permissionssetupprotocol.md |
Cross-workspace permissions |
upgrade.md |
Upgrade to latest version |
Logging & Debugging
| Reference | Purpose |
|---|---|
logging_protocol.md |
Hybrid logging v2.0 |
hybridloggingprotocol.md |
Detailed hybrid logging spec |
hookconfigurationcritical.md |
Hook setup requirements |
hookloggerenhancements.md |
Hook logger improvements |
preworkchecklist.md |
Code agent pre-work verification |
getunstuckprotocol.md |
Recovery from blockers |
resilience_protocol.md |
Error recovery patterns |
testing_protocol.md |
Progressive testing requirements |
OpenCode Integration
| Reference | Purpose |
|---|---|
opencodeintegrationquickstart.md |
Dual-mode quick start |
opencodesetupguide.md |
Full OpenCode setup |
opencodemigrationguide.md |
Migrate to OpenCode |
opencodeloggingprotocol.md |
OpenCode-specific logging |
opencodewrappersetup.md |
Wrapper script setup |
claudevsopencode_comparison.md |
Feature comparison |
Agent Configuration
| Reference | Purpose |
|---|---|
agent_specialization.md |
Agent role configuration |
codeagentclaude_template.md |
CLAUDE.md template for code agents |
codeagentagents_template.md |
AGENTS.md template for code agents |
Project Management
| Reference | Purpose |
|---|---|
gitprmanagement.md |
Git and PR workflow |
tickettrackingpr_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.