Architect Agent

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:

Decision Tree

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:

Critical Protocol: File Locations

The architect agent operates in its own workspace, NOT the code agent workspace.

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)

Setup & Configuration

Logging & Debugging

OpenCode Integration

Agent Configuration

Project Management

Guides Directory

Step-by-step workflows in guides/workflows/:

Templates

Ready-to-use workspace templates in templates/:

See: templates/README.md for usage instructions.

---

<!--

THIS FILE IS FOR THE ARCHITECT-AGENT SKILL REPOSITORY

This AGENTS.md defines git workflow requirements for THIS repository (the skill itself). This is NOT a template for user workspaces.

For templates to copy into your workspaces, see:

• templates/architect-workspace/AGENTS.md (for architect agent workspaces)
• templates/code-agent-workspace/AGENTS.md (for code agent workspaces)

-->

AGENTS.md - Agent Workflow Requirements

Purpose

This file provides instructions for AI agents (both architect agents and code agents) working with this skill. It defines mandatory workflow requirements that must be followed.

Git Workflow (MANDATORY)

CRITICAL: Never Commit Directly to Main

ALL changes must go through the branch → issue → PR workflow.

Required Steps for ALL Changes

1. Create Feature/Fix Branch

# For new features
git checkout -b feat/<short-description>

# For bug fixes
git checkout -b fix/<short-description>

Examples:

• feat/add-testing-protocol
• fix/workspace-confusion
• feat/improve-grading-rubric
• fix/typo-in-logging

2. Create GitHub Issue FIRST

Before making changes, create an issue describing:

gh issue create \
  --title "Clear, actionable title" \
  --body "## Problem
[What's wrong or what's needed]

## Root Cause (for bugs)
[Why this issue exists]

## Proposed Solution
[How to fix it]

## Impact
[What this affects]" \
  --label "bug,documentation"  # Choose appropriate labels

Issue should include:

• Clear problem statement
• Root cause analysis (for bugs)
• Proposed solution
• Expected behavior
• Impact assessment
• Affected components

3. Make Changes and Commit

git add <files>
git commit -m "type: brief summary

Fixes #<issue-number>

Detailed explanation:
- Change 1
- Change 2
- Why these changes were made
"

Commit message format:

• Type prefix: feat:, fix:, docs:, refactor:, test:
• Brief summary: One line description
• Issue reference: Fixes #<number> (MANDATORY)
• Detailed body: What changed and why

Example:

fix: clarify file location protocol to prevent workspace confusion

Fixes #2

Added explicit 'CRITICAL: File Location Protocol' section to SKILL.md
to prevent architect agents from writing to code agent workspace.

Changes:
- Added table of contents with warning
- Added visual workspace separation diagram
- Provided wrong vs correct examples
- Added checklist verification item

4. Push Branch

git push -u origin feat/<description>
# OR
git push -u origin fix/<description>

5. Create Pull Request

gh pr create \
  --title "Type: Clear description of change" \
  --body "## Fixes #<issue-number>

## Problem
[Brief description of what was wrong]

## Root Cause
[Why the issue existed]

## Solution
[What was changed to fix it]

### Key Changes
1. Change 1 - Description
2. Change 2 - Description

## Testing
[How the fix was verified]

## Impact
- **Prevents**: [What problems this prevents]
- **Improves**: [What this improves]
- **Affects**: [What components are affected]

## Files Changed
- \`file1.md\`: Description of changes (+X lines)
" \
  --base main

PR must include:

• Issue reference (Fixes #<number>)
• Problem description
• Root cause (for bugs)
• Solution explanation
• List of specific changes
• Testing/verification notes
• Impact assessment
• Files changed summary

Workflow Summary Diagram

1. Create Branch          →  git checkout -b feat/description
2. Create Issue           →  gh issue create (get issue #)
3. Make Changes           →  Edit files
4. Commit with Reference  →  git commit -m "Fixes #X"
5. Push Branch            →  git push -u origin feat/description
6. Create PR              →  gh pr create (references issue #)
7. Review & Merge         →  (after approval)

Why This Workflow is Mandatory

1. Review and Quality Control

• Changes are reviewed before merging
• Prevents mistakes from reaching main
• Allows discussion and improvement

2. Audit Trail and History

• Issues document why changes were needed
• PRs document what was changed
• Commits link to both
• Full context preserved forever

3. Tracking and Project Management

• Issues track work items
• PRs track implementations
• Easy to see what's in progress
• Easy to see what was completed

4. Safety and Reversibility

• Easy to revert if needed
• Changes are isolated
• Main branch stays stable
• Less risk of breaking changes

5. Collaboration

• Team can see what's happening
• Discussion happens in PR comments
• Multiple reviewers can provide input
• Knowledge sharing through documentation

Protection Rules

Main Branch Protection (Recommended)

Branch Protection Rules for 'main':
- Require pull request before merging
- Require approvals: 1
- Require status checks to pass
- Require branches to be up to date
- Do not allow bypassing

Enforcement

Agents MUST:

• ❌ NEVER commit directly to main
• ✅ ALWAYS create branch first
• ✅ ALWAYS create issue before changes
• ✅ ALWAYS reference issue in commit
• ✅ ALWAYS create PR with description
• ✅ ALWAYS wait for review before merge

If agent attempts direct commit to main:

• Stop the commit
• Create branch instead
• Follow proper workflow

Examples

Example 1: Bug Fix Workflow

# 1. Create branch
git checkout -b fix/workspace-location-confusion

# 2. Create issue
gh issue create \
  --title "Architect agents writing to code agent workspace" \
  --body "..." \
  --label "bug,documentation"
# Returns: Issue #2

# 3. Make changes
# Edit SKILL.md

# 4. Commit
git add SKILL.md
git commit -m "fix: clarify file location protocol

Fixes #2

Added explicit workspace separation section..."

# 5. Push
git push -u origin fix/workspace-location-confusion

# 6. Create PR
gh pr create \
  --title "Fix: Add explicit file location protocol" \
  --body "## Fixes #2
..." \
  --base main
# Returns: PR #3

Example 2: Feature Addition Workflow

# 1. Create branch
git checkout -b feat/add-error-recovery-protocol

# 2. Create issue
gh issue create \
  --title "Add error recovery protocol to references" \
  --body "..." \
  --label "enhancement,documentation"
# Returns: Issue #4

# 3. Make changes
# Create references/error_recovery.md

# 4. Commit
git add references/error_recovery.md
git commit -m "feat: add error recovery protocol

Fixes #4

Added comprehensive error recovery protocol document..."

# 5. Push
git push -u origin feat/add-error-recovery-protocol

# 6. Create PR
gh pr create \
  --title "Feat: Add error recovery protocol reference" \
  --body "## Fixes #4
..." \
  --base main
# Returns: PR #5

Quick Reference

Branch naming:

• Features: feat/<description>
• Fixes: fix/<description>

Always include in commits:

• Fixes #<number>

Always include in PRs:

• ## Fixes #<number>
• Problem description
• Solution description
• Testing notes
• Impact assessment

Never:

• ❌ Commit directly to main
• ❌ Skip issue creation
• ❌ Skip issue reference in commit
• ❌ Skip PR description

Grading Impact (for Code Agents)

Following this workflow affects grading:

Proper workflow (+5 points):

• Created issue before work
• Created branch properly
• Committed with issue reference
• Created PR with full description

Improper workflow (deductions):

• No issue created: -2 points
• Direct commit to main: -5 points
• No issue reference in commit: -2 points
• Incomplete PR description: -2 points

Related Documentation

• CLAUDE.md - Git workflow requirements (this document's companion)
• SKILL.md - Main architect agent skill documentation
• references/git_pr_management.md - Git and PR management details

<!--

THIS FILE IS FOR THE ARCHITECT-AGENT SKILL REPOSITORY

This CLAUDE.md configures the architect-agent skill workspace (THIS repository). This is NOT a template for user workspaces.

For templates to copy into your workspaces, see:

• templates/architect-workspace/CLAUDE.md (for architect agent workspaces)
• templates/code-agent-workspace/CLAUDE.md (for code agent workspaces)

-->

CLAUDE.md - Architect Agent Skill Workspace

Repository Purpose

This is the architect-agent skill workspace for Claude Code. This skill transforms AI agents into specialized architect agents that plan, delegate work to code agents, and grade completed implementations.

Git Workflow Requirements

CRITICAL: NEVER commit directly to main branch

Branch Naming Convention

All changes MUST be made on feature/fix branches:

• Feature branches: feat/<short-description>
• Example: feat/add-logging-protocol
• Example: feat/grading-rubric-update

• Bug fix branches: fix/<short-description>
• Example: fix/workspace-confusion
• Example: fix/file-naming-typo

Required Workflow Steps

1. Create branch from main

   git checkout main
   git pull origin main
   git checkout -b feat/your-feature-name
   # OR
   git checkout -b fix/your-bug-fix-name

2. Create GitHub issue FIRST

   gh issue create \
     --title "Clear description of problem or feature" \
     --body "Detailed description with problem, root cause, solution" \
     --label "bug,documentation"  # or appropriate labels

• Document the problem/feature clearly
• Explain root cause (for bugs)
• Describe proposed solution
• Note impact and affected components

3. Make changes and commit with issue reference

   git add <files>
   git commit -m "type: brief description

   Fixes #<issue-number>

   Detailed explanation of changes...
   "

• Commit message types: feat:, fix:, docs:, refactor:
• ALWAYS reference the issue with Fixes #<number>
• Include detailed explanation of what changed and why

4. Push branch and create PR

   git push -u origin feat/your-feature-name

   gh pr create \
     --title "Type: Clear description" \
     --body "## Fixes #<issue>

     ## Problem
     [Description]

     ## Solution
     [What was changed]

     ## Testing
     [How verified]

     ## Impact
     [What this affects]
     " \
     --base main

5. PR Requirements

• Must reference the issue (Fixes #<number>)
• Must describe the problem being solved
• Must explain the solution approach
• Must list specific changes made
• Must note testing/verification performed
• Must describe impact and affected components

Why This Workflow

1. Review: Changes can be reviewed before merging 2. Tracking: Issues and PRs create audit trail 3. Context: PR descriptions provide context for future reference 4. Safety: Prevents accidental direct commits to main 5. Collaboration: Allows discussion before merge

Protection Rules

• Main branch should be protected (no direct pushes)
• PRs should require review before merge
• All commits should reference issues
• Branch should be up to date before merge

Core Workflow Reference

For architect agent usage, see:

• SKILL.md - Main skill documentation
• README.md - Quick start guide
• references/ - Detailed protocols

Skill Usage Triggers

This skill activates ONLY when user explicitly requests: 1. "write instructions for code agent" 2. "this is a new architect agent, help me set it up" 3. "grade the code agent's work"

Do NOT activate for general architecture discussions or code exploration.

Contributing to Architect Agent Skill

Thank you for your interest in contributing! This guide explains the required workflow for all changes to this repository.

---

Table of Contents

• Git Workflow
• Branch Naming
• Issue Creation
• Commit Messages
• Pull Requests
• Why This Workflow
• Examples

---

Git Workflow

CRITICAL: NEVER commit directly to main branch

All changes MUST follow this workflow:

1. Create Branch          →  git checkout -b feat/description
2. Create Issue           →  gh issue create (document problem/feature)
3. Make Changes           →  Edit files
4. Commit with Reference  →  git commit -m "type: description\n\nFixes #X"
5. Push Branch            →  git push -u origin feat/description
6. Create PR              →  gh pr create (reference issue, explain changes)
7. Review & Merge         →  After approval

---

Branch Naming

Use descriptive branch names with appropriate prefixes:

Feature Branches

feat/<short-description>

Examples:

• feat/add-logging-protocol
• feat/grading-rubric-update
• feat/opencode-integration

Bug Fix Branches

fix/<short-description>

Examples:

• fix/workspace-confusion
• fix/file-naming-typo
• fix/broken-cross-reference

Documentation Branches

docs/<short-description>

Examples:

• docs/update-readme
• docs/add-contributing-guide

Refactoring Branches

refactor/<short-description>

Examples:

• refactor/reorganize-references
• refactor/simplify-skill-structure

---

Issue Creation

Create an issue BEFORE making changes.

Issue Template

gh issue create \
  --title "Clear, actionable title" \
  --body "## Problem
[What's wrong or what's needed]

## Root Cause (for bugs)
[Why this issue exists]

## Proposed Solution
[How to fix it]

## Impact
[What this affects]

## Related
[Links to related issues, PRs, or docs]" \
  --label "bug" \  # or "enhancement", "documentation", etc.

Good Issue Titles

✅ Good:

• "INSTALLATION.md should be in references/ directory"
• "Add upgrade trigger to SKILL.md"
• "Reference Documents section missing 17 files"

❌ Bad:

• "Fix stuff"
• "Update docs"
• "Improvements"

Issue Body Should Include

1. Problem: Clear description of what's wrong or needed 2. Root Cause: Why this issue exists (for bugs) 3. Proposed Solution: How you plan to fix it 4. Impact: What components/workflows this affects 5. Related: Links to related issues or docs

---

Commit Messages

Format

type: brief summary (50 chars max)

Fixes #<issue-number>

Detailed explanation:
- Change 1
- Change 2
- Why these changes were made

Additional context...

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring (no functionality change)
• test: Adding or updating tests
• chore: Maintenance tasks

Examples

Feature:

git commit -m "feat: add upgrade trigger to SKILL.md

Fixes #14

Added Trigger 6 for upgrade workflow:
- User says 'upgrade to latest architect agent protocol'
- References upgrade.md in references/
- Includes prerequisite check for version detection"

Bug Fix:

git commit -m "fix: move INSTALLATION.md to references/

Fixes #12

Moved INSTALLATION.md to references/installation.md:
- Preserves git history with git mv
- Updates all cross-references
- Aligns with file organization standards from SPEC.md"

Documentation:

git commit -m "docs: create references/README.md index

Fixes #15

Created comprehensive reference index:
- All 29 files cataloged by category
- Quick navigation section
- When-to-use guidance for each file
- File organization diagram"

Rules

1. Always include Fixes #<issue-number> 2. Use imperative mood: "add feature" not "added feature" 3. Brief summary: 50 characters max 4. Detailed body: Explain what and why, not how 5. Reference related issues: If fixing multiple, list all

---

Pull Requests

Creating a PR

gh pr create \
  --title "Type: Clear description of change" \
  --body "## Fixes #<issue-number>

## Problem
[Brief description of what was wrong]

## Root Cause
[Why the issue existed - for bug fixes]

## Solution
[What was changed to fix it]

### Key Changes
1. Change 1 - Description
2. Change 2 - Description
3. Change 3 - Description

## Testing
[How the fix was verified]

## Impact
- **Prevents**: [What problems this prevents]
- **Improves**: [What this improves]
- **Affects**: [What components are affected]

## Files Changed
- \`file1.md\`: Description of changes (+X lines)
- \`file2.md\`: Description of changes (+X lines)" \
  --base main

PR Requirements

MUST include:

• Issue reference (Fixes #<number>)
• Problem description
• Root cause (for bugs)
• Solution explanation
• List of specific changes
• Testing/verification notes
• Impact assessment
• Files changed summary

MUST NOT:

• Skip issue reference
• Have incomplete description
• Merge without review (if collaboration)
• Push directly to main

---

Why This Workflow

1. Review and Quality Control

• Changes are reviewed before merging
• Prevents mistakes from reaching main
• Allows discussion and improvement

2. Audit Trail and History

• Issues document why changes were needed
• PRs document what was changed
• Commits link to both
• Full context preserved forever

3. Tracking and Project Management

• Issues track work items
• PRs track implementations
• Easy to see what's in progress
• Easy to see what was completed

4. Safety and Reversibility

• Easy to revert if needed
• Changes are isolated
• Main branch stays stable
• Less risk of breaking changes

5. Collaboration

• Team can see what's happening
• Discussion happens in PR comments
• Multiple reviewers can provide input
• Knowledge sharing through documentation

---

Examples

Example 1: Feature Addition

# 1. Create branch
git checkout main
git pull origin main
git checkout -b feat/add-spec-document

# 2. Create issue
gh issue create \
  --title "Add SPEC.md project specification document" \
  --body "## Problem
No central specification document defining project scope, architecture, and standards.

## Proposed Solution
Create SPEC.md covering:
- Purpose and scope
- Architecture (3-level progressive disclosure)
- Quality standards
- File organization standards

## Impact
Provides north star for all future development decisions." \
  --label "enhancement,documentation"

# Returns: Issue #10

# 3. Make changes
# ... create SPEC.md ...

# 4. Commit
git add SPEC.md
git commit -m "feat: add SPEC.md project specification

Fixes #10

Created comprehensive project specification:
- Purpose and vision
- Scope and boundaries
- Three-level architecture
- Key workflows
- Quality standards
- Decision framework"

# 5. Push
git push -u origin feat/add-spec-document

# 6. Create PR
gh pr create \
  --title "Feat: Add SPEC.md project specification" \
  --body "## Fixes #10

## Problem
The skill lacked a central specification document, making it difficult to maintain consistency and make architectural decisions.

## Solution
Created SPEC.md covering all aspects of the project:

### Key Sections
1. Purpose & Vision - What the skill does
2. Scope & Boundaries - What's in/out of scope
3. Architecture - 3-level progressive disclosure
4. Key Workflows - Core operations
5. Quality Standards - What good looks like
6. Decision Framework - How to evaluate changes

## Testing
Validated structure against existing documentation and references.

## Impact
- **Provides**: North star for future development
- **Improves**: Consistency in updates
- **Affects**: All future feature additions and changes

## Files Changed
- \`SPEC.md\`: New file (+500 lines)" \
  --base main

# Returns: PR #11

Example 2: Bug Fix

# 1. Create branch
git checkout main
git pull origin main
git checkout -b fix/installation-location

# 2. Create issue
gh issue create \
  --title "INSTALLATION.md should be in references/ directory" \
  --body "## Problem
INSTALLATION.md is in root but should be in references/ for consistency.

## Root Cause
File was created in root initially without considering organization standards.

## Proposed Solution
Move INSTALLATION.md to references/installation.md using git mv.

## Impact
Aligns with file organization standards from SPEC.md." \
  --label "bug,refactor"

# Returns: Issue #12

# 3. Make changes
git mv INSTALLATION.md references/installation.md

# 4. Commit
git commit -m "fix: move INSTALLATION.md to references/

Fixes #12

Moved to align with file organization standards:
- Preserves git history
- Consistent with other reference docs
- Matches SPEC.md file organization"

# 5. Push
git push -u origin fix/installation-location

# 6. Create PR
gh pr create \
  --title "Fix: Move INSTALLATION.md to references/" \
  --body "## Fixes #12

## Problem
INSTALLATION.md was in root directory instead of references/.

## Root Cause
Initial file creation didn't follow organization standards.

## Solution
Moved file to correct location:

### Key Changes
1. `git mv INSTALLATION.md references/installation.md` - Preserves history
2. Updated all cross-references in README.md
3. Updated SKILL.md references

## Testing
Verified all links still work after move.

## Impact
- **Prevents**: Confusion about file organization
- **Improves**: Consistency with SPEC.md standards
- **Affects**: Documentation structure

## Files Changed
- \`INSTALLATION.md\` → \`references/installation.md\` (renamed)" \
  --base main

---

Code of Conduct

• Be respectful and constructive
• Focus on the work, not the person
• Provide specific, actionable feedback
• Assume good intent
• Follow the workflow - no exceptions

---

Questions?

If you're unsure about any aspect of the workflow:

1. Check CLAUDE.md for git workflow overview 2. Check AGENTS.md for detailed requirements 3. Check SPEC.md for architectural guidance 4. Create an issue to ask for clarification

---

Summary Checklist

Before submitting a PR:

• [ ] Created branch with appropriate prefix
• [ ] Created issue documenting problem/feature
• [ ] Made focused changes (one issue per branch)
• [ ] Committed with issue reference (Fixes #X)
• [ ] Pushed branch to origin
• [ ] Created PR with complete description
• [ ] PR references issue
• [ ] PR explains problem, solution, and impact
• [ ] All cross-references updated
• [ ] Ready for review

---

Last Updated: 2025-01-21 Version: 4.0

Log Session: test-session

Started: 2025-01-17 14:23:00

Goal

[Document your goal here]

Success Criteria

• [ ] Criterion 1
• [ ] Criterion 2

---

[14:23:05] 🎯 DECISION: This is a test decision

--- [14:30:00] 🏁 Final Summary Status: ✅ COMPLETE Completed: 2025-01-17 14:30:00 ---

OpenCode Integration Test Suite

Purpose: Verify OpenCode hooks and logging work correctly in architect→code agent workflow Test Coverage: 4 scenarios covering basic logging, decision logging, research orchestration, and full workflow Estimated Time: 10-15 minutes

---

Test Environment

These tests create temporary workspaces and verify:

• TypeScript plugin logs automatically
• Bash wrapper scripts log correctly
• Manual decision logging works
• Session management functions properly
• Cross-workspace access works
• Log format matches Claude Code format

---

Prerequisites

• OpenCode installed: opencode --version should work
• Architect-agent skill: Available at ~/.claude/skills/architect-agent
• Bash: Tests use bash scripts
• jq (optional): For JSON validation

---

Quick Start

# Run all tests
cd ~/.claude/skills/architect-agent/docs/testing/opencode-integration-test
./run-all-tests.sh

# Or run individual tests
./test-scenarios/01-basic-logging.sh
./test-scenarios/02-decision-logging.sh
./test-scenarios/03-get-unstuck.sh
./test-scenarios/04-full-workflow.sh

---

Test Scenarios

01: Basic Logging Test

File: test-scenarios/01-basic-logging.sh

Tests:

• Log session can be started
• Active log file is created and tracked
• Session can be completed
• Log file has correct format

Expected Duration: 30 seconds

Success Criteria:

• ✅ Log file created in debugging/logs/
• ✅ debugging/current_log_file.txt points to active log
• ✅ Log contains session header
• ✅ Session completes and clears active log

---

02: Decision Logging Test

File: test-scenarios/02-decision-logging.sh

Tests:

• log-decision.sh script works
• All decision types log correctly (decision, rationale, investigation, verification, deviation, milestone)
• Timestamps are in correct format [HH:MM:SS]
• Emoji markers present

Expected Duration: 1 minute

Success Criteria:

• ✅ All 6 decision types logged
• ✅ Timestamps match [HH:MM:SS] format
• ✅ Emoji markers present: 🎯 💭 🔍 ✓ ⚠️ 🏁
• ✅ Log entries readable and well-formatted

---

03: Get Unstuck Test

File: test-scenarios/03-get-unstuck.sh

Tests:

• get-unstuck.sh script works
• Research orchestration functions
• Logs decisions and findings

Expected Duration: 2 minutes (actual research time varies)

Success Criteria:

• ✅ Script executes without errors
• ✅ Research plan created
• ✅ Findings logged with log-decision.sh
• ✅ Multiple research channels attempted

Note: This test may require network access for actual research. Can be run in mock mode.

---

04: Full Workflow Test

File: test-scenarios/04-full-workflow.sh

Tests:

• Complete architect→code agent workflow
• Session start → decision logging → automated command logging → session complete
• Both plugin and wrapper approaches
• Cross-workspace access

Expected Duration: 3 minutes

Success Criteria:

• ✅ Full session lifecycle works
• ✅ Manual decisions logged
• ✅ Automated commands logged (plugin or wrapper)
• ✅ Log format matches expected output
• ✅ Architect can read code agent logs

---

Test Workspace Structure

Tests create temporary workspaces:

/tmp/opencode-test-XXXXXX/
├── architect-workspace/
│   ├── instructions/
│   │   └── test-instruction.md
│   └── human/
│       └── test-summary.md
└── code-agent-workspace/
    ├── .opencode/
    │   ├── opencode.json
    │   └── plugins/
    │       └── logger/
    │           └── index.ts
    ├── debugging/
    │   ├── current_log_file.txt
    │   ├── logs/
    │   ├── scripts/
    │   │   ├── log-start.sh
    │   │   ├── log-complete.sh
    │   │   ├── log-decision.sh
    │   │   └── get-unstuck.sh
    │   └── wrapper-scripts/
    │       ├── run-with-logging.sh
    │       ├── log-tool-call.sh
    │       └── log-tool-result.sh
    └── test-files/
        └── sample.txt

---

Running Tests

Run All Tests

./run-all-tests.sh

Output:

🧪 OpenCode Integration Test Suite
=====================================

Test 01: Basic Logging................ ✅ PASS
Test 02: Decision Logging............. ✅ PASS
Test 03: Get Unstuck.................. ✅ PASS
Test 04: Full Workflow................ ✅ PASS

=====================================
Results: 4/4 tests passed
Duration: 6m 32s

Run Individual Test

./test-scenarios/01-basic-logging.sh

Output:

🧪 Test 01: Basic Logging
========================

Setting up test workspace...
Testing log session start...
Testing log session complete...
Verifying log format...

✅ All checks passed

Run with Verbose Output

VERBOSE=1 ./test-scenarios/01-basic-logging.sh

Shows detailed output of each step.

---

Verifying Results

Manual Verification

After running tests, check:

# List generated log files
ls -lt /tmp/opencode-test-*/code-agent-workspace/debugging/logs/

# View a log file
cat /tmp/opencode-test-*/code-agent-workspace/debugging/logs/log-*.md

# Compare to expected output
diff <expected-output-file> <actual-log-file>

Expected Log Format

See expected-outputs/ directory for reference log files:

expected-outputs/
├── basic-log-sample.md
├── decision-log-sample.md
├── get-unstuck-log-sample.md
└── full-workflow-log.md

---

Troubleshooting

Test Fails: "OpenCode not found"

Cause: OpenCode not installed or not in PATH

Fix:

# Verify OpenCode installation
which opencode

# Install OpenCode if needed
# (follow OpenCode installation instructions)

Test Fails: "Permission denied"

Cause: Test scripts not executable

Fix:

chmod +x test-scenarios/*.sh
chmod +x run-all-tests.sh

Test Fails: "Plugin not working"

Cause: OpenCode version doesn't support plugins

Fix:

• Update OpenCode to latest version
• Or: Tests will fallback to wrapper scripts automatically

Test Fails: "Log format mismatch"

Cause: Timestamps or format differ from expected

Fix:

• Check if timezone affects timestamp format
• Verify log-decision.sh copied correctly
• Compare actual vs expected manually

---

Cleanup

Tests create temporary workspaces in /tmp/. To clean up:

# Remove all test workspaces
rm -rf /tmp/opencode-test-*

# Or let OS clean up /tmp/ automatically (recommended)

---

CI/CD Integration

To run tests in CI/CD pipeline:

#!/bin/bash
# .github/workflows/test-opencode.yml

- name: Run OpenCode Integration Tests
  run: |
    cd docs/testing/opencode-integration-test
    ./run-all-tests.sh
    exit $?

---

Test Development

Adding New Tests

1. Create test script: test-scenarios/05-my-test.sh 2. Follow template from existing tests 3. Add to run-all-tests.sh 4. Create expected output: expected-outputs/my-test-sample.md 5. Document in this README

Test Script Template

#!/bin/bash
# Test NN: Description

set -euo pipefail

source ../test-lib.sh  # Common test functions

# Setup
setup_test_workspace

# Test steps
log "Testing feature X..."
# ... test code ...

# Verify
verify_log_format
verify_feature_specific_thing

# Cleanup
cleanup_test_workspace

# Report
report_success

---

Related Documentation

• OpenCode Logging Protocol
• OpenCode Setup Guide
• Test Results - Latest test run results

---

Version: 1.0 Last Updated: 2025-01-17

Skill Evaluation Report: architect-agent

Evaluated: 2025-12-31 Files Reviewed: SKILL.md, guides/workflows/.md, references/.md (30+ files), examples/human-instructions/.md, templates/.sh

---

Overall Score: 88/100

Grade: B

Code Quality: 22/25 (scripts present)

---

Executive Summary

The architect-agent skill is a well-structured, production-ready skill that effectively coordinates multi-agent workflows. Its primary strength is excellent discoverability with 5+ trigger phrases and clear intent classification. The most impactful improvement would be adding optional fields (allowed-tools, metadata with version) and exposing more references in the main SKILL.md to improve navigation. This skill is ready for production use with minor enhancements recommended.

---

Detailed Scores

Progressive Disclosure Architecture (26/30)

Ease of Use (23/25)

Spec Compliance (13/15)

Writing Style (9/10)

Utility (19/20)

Modifiers Applied (+6)

Penalties: None

Bonuses:

• Copy-paste checklists: +2 (multiple workflow checklists)
• Self-documenting scripts: +2 (setup-workspace.sh has usage info)
• Explicit scope boundaries: +1 ("DO NOT Trigger For" section)
• Counter-examples: +1 (BAD-vague-summary.md)

---

Critical Issues (Top 7)

Issue 1: No Optional Fields in Frontmatter

Severity: Medium Location: SKILL.md:frontmatter Pillar Affected: Spec Compliance

Problem: Skill doesn't use optional fields like allowed-tools or metadata, missing opportunities for version tracking and tool restrictions.

Current:

---
name: architect-agent
description: Coordinates planning, delegation, and evaluation...
---

Suggested Rewrite:

---
name: architect-agent
description: Coordinates planning, delegation, and evaluation across architect and code agent workspaces. Use when asked to "write instructions for code agent", "initialize architect workspace", "grade code agent work", "send instructions", or "verify code agent setup".
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
metadata:
  version: 3.0.0
  last-updated: 2025-12-31
---

Impact: +2 points (optional fields + version bonus)

---

Issue 2: Hidden References Not Surfaced

Severity: Medium Location: SKILL.md:Reference Directory Pillar Affected: PDA, Ease of Use

Problem: Only 11 of 30+ references are listed in the Reference Directory table. Critical files like resilience_protocol.md, quick_start.md, and agent_specialization.md are not discoverable from SKILL.md.

Current:

## Reference Directory

All detailed protocols are in `references/`:

| Reference | Purpose |
|-----------|---------|
| `instruction_structure.md` | Complete instruction file template (for code agents) |
... (11 total)

Suggested Rewrite:

## Reference Directory

All detailed protocols are in `references/`:

### Core References (Always Relevant)

| Reference | Purpose |
|-----------|---------|
| `instruction_structure.md` | Code agent instruction template |
| `human_instruction_structure.md` | Human-executable instruction template |
| `grading_rubrics.md` | 6-category grading criteria |
| `file_naming.md` | Timestamp and naming conventions |

### Setup & Configuration

| Reference | Purpose |
|-----------|---------|
| `installation.md` | Skill installation guide |
| `quick_start.md` | Fast-track setup guide |
| `workspace_setup_complete.md` | Full workspace initialization |
| `permissions_setup_protocol.md` | Cross-workspace permissions |

### Logging & Debugging

| Reference | Purpose |
|-----------|---------|
| `logging_protocol.md` | Hybrid logging v2.0 |
| `hook_configuration_critical.md` | Hook setup requirements |
| `get_unstuck_protocol.md` | Recovery from blockers |
| `resilience_protocol.md` | Error recovery patterns |

### Advanced Topics

| Reference | Purpose |
|-----------|---------|
| `opencode_integration_quickstart.md` | Dual-mode setup |
| `agent_specialization.md` | Agent role configuration |

Impact: +3 points (layered structure, discoverability)

---

Issue 3: Second-Person Voice in Critical Protocol

Severity: Low Location: SKILL.md:93-108 Pillar Affected: Writing Style

Problem: Section uses second-person "YOU" which is inconsistent with imperative voice best practices.

Current:

## Critical Protocol: File Locations

**YOU ARE THE ARCHITECT AGENT - You work in YOUR workspace, NOT the code agent workspace.**

| What | Where YOU Write | Where Code Agent Works |

Suggested Rewrite:

## Critical Protocol: File Locations

**The architect agent works in its own workspace, NOT the code agent workspace.**

| What | Architect Writes To | Code Agent Workspace |
|------|-------------------|---------------------|
| 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 `debugging/logs/` |

**Guard Rail:** If writing to code agent's workspace, stop and verify the operation.

Impact: +1 point (voice & tense)

---

Issue 4: Decision Tree Could Be a Table

Severity: Low Location: SKILL.md:36-71 Pillar Affected: PDA (Navigation Signals)

Problem: ASCII art decision tree is 35 lines long and harder to scan than a table. Tables are more grep-friendly and fit the document style.

Current:

USER REQUEST
    │
    ├─► "write/create instructions" OR "delegate"
    │   └─► Check: instructions/ dir exists?
    │       ├─► Yes → Load guides/workflows/create-instructions.md
    │       └─► No → Suggest workspace initialization first
    ... (35 lines)

Suggested Rewrite:

## 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` |
| "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` |

Impact: +1 point (navigation signals)

---

Issue 5: Missing Version Information

Severity: Low Location: SKILL.md:frontmatter Pillar Affected: Spec Compliance

Problem: No version tracking makes it difficult to know which version is deployed or to track changes over time.

Current: No version information anywhere in frontmatter.

Suggested Rewrite: Add to frontmatter (see Issue 1), plus add to SKILL.md body:

---

**Version:** 3.0.0 | [Changelog](references/CHANGELOG.md)

Impact: +1 point (version in metadata bonus)

---

Issue 6: No Quick Start in SKILL.md Overview

Severity: Low Location: SKILL.md:top Pillar Affected: Ease of Use

Problem: New users must read through intent classification before understanding what this skill does. A 2-sentence quick start would help.

Current:

# Architect Agent Workflow Skill

Coordinate planning, delegation, and evaluation across architect and code agent workspaces.

## Table of Contents
...

Suggested Rewrite:

# Architect Agent Workflow Skill

Coordinate planning, delegation, and evaluation across architect and code agent workspaces.

**Quick Start:** Run `/architect-agent` with one of: "write instructions", "initialize workspace", "grade work", or "send instructions". See [Quick Setup](#quick-setup-template-based) for template-based initialization.

## Table of Contents
...

Impact: +1 point (workflow clarity, first-time user experience)

---

Issue 7: Guides Directory Could Link to Templates

Severity: Low Location: SKILL.md:154-163 Pillar Affected: Utility

Problem: Guides Directory lists workflows but doesn't mention the relationship to templates. Users may not realize templates exist.

Current:

## Guides Directory

Step-by-step workflows in `guides/workflows/`:

| Guide | Trigger |
|-------|---------|
| `create-instructions.md` | "write instructions for code agent" |
...

Suggested Rewrite:

## 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:** Use `templates/setup-workspace.sh` for automated workspace creation. See `templates/README.md`.

Impact: +0.5 points (examples & templates discoverability)

---

General Recommendations

1. Add optional fields to frontmatter: Include allowed-tools to document which tools this skill uses, and metadata.version for tracking.

2. Surface all references: Create categorized sections in Reference Directory to expose all 30+ reference files, not just 11.

3. Standardize voice: Replace "YOU ARE THE ARCHITECT" with imperative/third-person phrasing for consistency.

4. Add quick start line: One sentence at the top helps new users understand the skill immediately.

5. Consider a CHANGELOG.md: Track changes across versions for users who need to understand updates.

---

Score Improvement Roadmap

---

Grade Scale

---

Code Quality Assessment (22/25)

Scripts reviewed: templates/setup-workspace.sh, templates/verify-workspace.sh, logging scripts

---

JSON Output

{
  "skill_name": "architect-agent",
  "evaluated_at": "2025-12-31T12:00:00Z",
  "files_reviewed": ["SKILL.md", "guides/workflows/create-instructions.md", "guides/workflows/grade-work.md", "guides/workflows/send-instructions.md", "guides/workflows/initialize-workspace.md", "references/instruction_structure.md", "references/human_instruction_structure.md", "examples/human-instructions/GOOD-database-migration.md", "examples/human-instructions/BAD-vague-summary.md", "templates/setup-workspace.sh"],

  "scores": {
    "pda": {
      "total": 26,
      "max": 30,
      "breakdown": {
        "token_economy": { "score": 9, "max": 10, "assessment": "Excellent conciseness, tables used efficiently" },
        "layered_structure": { "score": 8, "max": 10, "assessment": "Good but 30+ refs with only 11 surfaced" },
        "reference_depth": { "score": 5, "max": 5, "assessment": "All references one level deep" },
        "navigation_signals": { "score": 4, "max": 5, "assessment": "Has TOC, decision tree could be table" }
      }
    },
    "ease_of_use": {
      "total": 23,
      "max": 25,
      "breakdown": {
        "metadata_quality": { "score": 9, "max": 10, "assessment": "5 trigger phrases, no optional fields" },
        "discoverability": { "score": 5, "max": 6, "assessment": "Clear triggers but hidden references" },
        "terminology_consistency": { "score": 4, "max": 4, "assessment": "Consistent terminology throughout" },
        "workflow_clarity": { "score": 5, "max": 5, "assessment": "Clear steps, checklists, conditional paths" }
      }
    },
    "spec_compliance": {
      "total": 13,
      "max": 15,
      "breakdown": {
        "frontmatter_validity": { "score": 5, "max": 5, "assessment": "Valid YAML, required fields present" },
        "name_conventions": { "score": 4, "max": 4, "assessment": "Hyphen-case, matches directory" },
        "description_quality": { "score": 4, "max": 4, "assessment": "5 trigger phrases, third-person" },
        "optional_fields": { "score": 0, "max": 2, "assessment": "No optional fields used" }
      }
    },
    "writing_style": {
      "total": 9,
      "max": 10,
      "breakdown": {
        "voice_and_tense": { "score": 3, "max": 4, "assessment": "Mostly imperative, some second-person" },
        "objectivity": { "score": 3, "max": 3, "assessment": "No marketing language" },
        "conciseness": { "score": 3, "max": 3, "assessment": "Every sentence adds value" }
      }
    },
    "utility": {
      "total": 19,
      "max": 20,
      "breakdown": {
        "problem_solving_power": { "score": 7, "max": 8, "assessment": "Addresses real multi-agent coordination gap" },
        "degrees_of_freedom": { "score": 5, "max": 5, "assessment": "Appropriate flexibility and constraints" },
        "feedback_loops": { "score": 4, "max": 4, "assessment": "Checklists, grading rubrics, validation" },
        "examples_and_templates": { "score": 3, "max": 3, "assessment": "Full templates, GOOD/BAD examples" }
      }
    }
  },

  "modifiers": {
    "penalties": [],
    "bonuses": [
      { "name": "copy_paste_checklists", "points": 2 },
      { "name": "self_documenting_scripts", "points": 2 },
      { "name": "explicit_scope_boundaries", "points": 1 },
      { "name": "counter_examples", "points": 1 }
    ],
    "net": 6
  },

  "final_score": 88,
  "grade": "B",

  "critical_issues": [
    {
      "rank": 1,
      "title": "No optional fields in frontmatter",
      "severity": "Medium",
      "location": "SKILL.md:frontmatter",
      "pillar": "Spec Compliance",
      "problem": "Missing allowed-tools and metadata.version",
      "current": "name: architect-agent\ndescription: ...",
      "suggested": "name: architect-agent\ndescription: ...\nallowed-tools:\n  - Read\n  - Write\n  - Bash\nmetadata:\n  version: 3.0.0",
      "impact": "+2 points"
    },
    {
      "rank": 2,
      "title": "Hidden references not surfaced",
      "severity": "Medium",
      "location": "SKILL.md:Reference Directory",
      "pillar": "PDA",
      "problem": "Only 11 of 30+ references listed",
      "current": "11 references in table",
      "suggested": "Categorized sections for all references",
      "impact": "+3 points"
    },
    {
      "rank": 3,
      "title": "Second-person voice in Critical Protocol",
      "severity": "Low",
      "location": "SKILL.md:93-108",
      "pillar": "Writing Style",
      "problem": "Uses YOU ARE instead of imperative",
      "current": "YOU ARE THE ARCHITECT AGENT",
      "suggested": "The architect agent works in its own workspace",
      "impact": "+1 point"
    },
    {
      "rank": 4,
      "title": "Decision tree could be a table",
      "severity": "Low",
      "location": "SKILL.md:36-71",
      "pillar": "PDA",
      "problem": "ASCII art is 35 lines, harder to scan",
      "current": "ASCII decision tree",
      "suggested": "Table with Intent, Pre-condition, Action columns",
      "impact": "+1 point"
    },
    {
      "rank": 5,
      "title": "Missing version information",
      "severity": "Low",
      "location": "SKILL.md:frontmatter",
      "pillar": "Spec Compliance",
      "problem": "No version tracking",
      "current": "No version",
      "suggested": "metadata.version: 3.0.0",
      "impact": "+1 point"
    },
    {
      "rank": 6,
      "title": "No quick start in overview",
      "severity": "Low",
      "location": "SKILL.md:top",
      "pillar": "Ease of Use",
      "problem": "New users must read through to understand",
      "current": "Direct to TOC",
      "suggested": "Add Quick Start one-liner after description",
      "impact": "+1 point"
    },
    {
      "rank": 7,
      "title": "Guides don't link to templates",
      "severity": "Low",
      "location": "SKILL.md:154-163",
      "pillar": "Utility",
      "problem": "Templates not discoverable from guides section",
      "current": "No mention of templates",
      "suggested": "Add templates reference below guides table",
      "impact": "+0.5 points"
    }
  ],

  "recommendations": [
    "Add optional fields (allowed-tools, metadata.version) to frontmatter",
    "Surface all references in categorized sections",
    "Standardize to imperative voice throughout",
    "Add quick start line at top for new users",
    "Consider adding CHANGELOG.md for version tracking"
  ],

  "code_quality": {
    "total": 22,
    "max": 25,
    "breakdown": {
      "error_handling": { "score": 7, "max": 8, "assessment": "set -e, validates inputs, clear errors" },
      "documentation": { "score": 6, "max": 6, "assessment": "Usage info, inline comments, version" },
      "dependency_management": { "score": 4, "max": 5, "assessment": "Assumes bash/git, no install cmds" },
      "script_organization": { "score": 5, "max": 6, "assessment": "Good structure, some long functions" }
    }
  }
}

BAD EXAMPLE - Do Not Follow This Pattern

This file demonstrates what NOT to do when creating human instructions.

---

The Problematic "Summary" Approach

Below is an example of human instructions that fail because they're summaries, not executable documentation:

# Database Migration Summary

## Main Objectives
- Add last_login_at column to users table
- Create index for performance

## Key Requirements
- PostgreSQL database
- Admin access

## Execution Flow
1. Back up the database
2. Run the migration
3. Verify it worked

## Success Criteria
- Column exists
- Index exists

---

Why This Fails

Problem 1: No Copy-Pasteable Commands

The instruction says "Back up the database" but doesn't provide:

# What command? pg_dump? Which flags? Where does it save?
pg_dump $DATABASE_URL --table=users --data-only --file="backup.sql"

A human reading "back up the database" has to: 1. Figure out which backup tool to use 2. Look up the syntax 3. Decide what options to use 4. Hope they got it right

Problem 2: No Expected Output

"Verify it worked" gives no indication of what success looks like:

• What query should they run?
• What result should they see?
• How do they know if something went wrong?

Problem 3: No Troubleshooting

When (not if) something fails, the human has no guidance:

• What are common errors?
• What causes each error?
• How do they fix it?

Problem 4: No Context/Why

Humans make better decisions when they understand purpose:

• Why are we adding this column?
• Why does the index need to be descending?
• Why do we use CONCURRENTLY?

Problem 5: Missing Prerequisites

"PostgreSQL database" and "Admin access" are vague:

• Which PostgreSQL version?
• What specific privileges are needed?
• What environment variables should be set?

---

The Fix

Compare with the GOOD example: GOOD-database-migration.md

Each step in the good example includes: 1. Commands - Exact bash commands to copy and run 2. Expected Output - What success looks like 3. Verification - How to confirm it worked 4. Why This Step - Context for decision-making 5. If This Fails - Troubleshooting table

---

Quick Checklist: Is This Executable?

Ask yourself these questions:

If you answer "No" to any of these, the instructions need more detail.

Database Schema Migration - Manual Execution Guide

Date: 2025-12-31 Estimated Time: 15 minutes Difficulty: Medium Corresponding Code Agent Instructions: instructions/instruct-20251231_143000-db-migration.md

---

Prerequisites

Before starting, ensure:

• [ ] PostgreSQL 14+ is installed and running
• [ ] You have admin access to the database
• [ ] A backup of the current database exists
• [ ] No active transactions are running against the database

Environment Setup

# Set database connection (adjust for your environment)
export DATABASE_URL="postgresql://admin:secret@localhost:5432/myapp_dev"

# Verify you can connect
psql $DATABASE_URL -c "SELECT version();"

Expected output:

                                   version
---------------------------------------------------------------------------
 PostgreSQL 14.5 on x86_64-apple-darwin21.6.0, compiled by Apple clang...

---

Overview

What This Accomplishes

This migration adds a last_login_at timestamp column to the users table and creates an index for efficient querying of recent logins. This supports the new "active users" dashboard feature.

What You'll Do

1. Create a backup of the users table 2. Add the new column with a default value 3. Create an index for query performance 4. Verify the migration succeeded

---

Step 1: Create Backup

Why This Step

Before modifying any schema, we create a backup so we can restore if something goes wrong. This is especially important for the users table since it contains critical authentication data.

Commands

# Create a timestamped backup of the users table
BACKUP_FILE="users_backup_$(date +%Y%m%d_%H%M%S).sql"

pg_dump $DATABASE_URL \
  --table=users \
  --data-only \
  --file="$BACKUP_FILE"

echo "Backup created: $BACKUP_FILE"

Expected Output

Backup created: users_backup_20251231_143022.sql

Verification

# Confirm backup file exists and has content
ls -la users_backup_*.sql
wc -l users_backup_*.sql

Expected:

-rw-r--r--  1 user  staff  45231 Dec 31 14:30 users_backup_20251231_143022.sql
    1247 users_backup_20251231_143022.sql

If This Fails

---

Step 2: Add Column

Why This Step

We add the last_login_at column with a NULL default so existing rows don't need immediate values. Using IF NOT EXISTS makes this idempotent - safe to run multiple times.

Commands

psql $DATABASE_URL << 'EOF'
-- Add the new column (idempotent)
ALTER TABLE users
ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMP WITH TIME ZONE;

-- Verify column was added
SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_name = 'users' AND column_name = 'last_login_at';
EOF

Expected Output

ALTER TABLE
 column_name   |        data_type         | is_nullable
---------------+--------------------------+-------------
 last_login_at | timestamp with time zone | YES
(1 row)

Verification

# Double-check the column exists with correct type
psql $DATABASE_URL -c "\d users" | grep last_login_at

Expected:

 last_login_at     | timestamp with time zone |           |          |

If This Fails

---

Step 3: Create Index

Why This Step

We create an index on last_login_at because the active users dashboard will query WHERE last_login_at > NOW() - INTERVAL '30 days'. Without an index, this query would do a full table scan.

Commands

psql $DATABASE_URL << 'EOF'
-- Create index for efficient date range queries
-- CONCURRENTLY prevents locking the table during creation
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_last_login_at
ON users (last_login_at DESC NULLS LAST);

-- Verify index was created
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'users' AND indexname = 'idx_users_last_login_at';
EOF

Expected Output

CREATE INDEX
       indexname           |                           indexdef
---------------------------+--------------------------------------------------------------
 idx_users_last_login_at   | CREATE INDEX idx_users_last_login_at ON public.users USING btree (last_login_at DESC NULLS LAST)
(1 row)

Verification

# Confirm index is valid (not in-progress or invalid)
psql $DATABASE_URL -c "SELECT indexrelid::regclass, indisvalid FROM pg_index WHERE indexrelid = 'idx_users_last_login_at'::regclass;"

Expected:

        indexrelid         | indisvalid
---------------------------+------------
 idx_users_last_login_at   | t
(1 row)

If This Fails

---

Final Verification

After completing all steps, verify the entire migration succeeded:

psql $DATABASE_URL << 'EOF'
-- Comprehensive verification
SELECT
  (SELECT COUNT(*) FROM information_schema.columns
   WHERE table_name = 'users' AND column_name = 'last_login_at') as column_exists,
  (SELECT COUNT(*) FROM pg_indexes
   WHERE tablename = 'users' AND indexname = 'idx_users_last_login_at') as index_exists;
EOF

Expected Final State

If both values are 1, the migration was successful.

---

Rollback Procedure

If something goes wrong and you need to undo the migration:

# Remove the index
psql $DATABASE_URL -c "DROP INDEX IF EXISTS idx_users_last_login_at;"

# Remove the column
psql $DATABASE_URL -c "ALTER TABLE users DROP COLUMN IF EXISTS last_login_at;"

# If data was corrupted, restore from backup
psql $DATABASE_URL < users_backup_20251231_143022.sql

---

Summary

---

Next Steps

After completing this task:

• [ ] Notify backend team that migration is complete
• [ ] Update API endpoint to populate last_login_at on login
• [ ] Deploy the active users dashboard feature
• [ ] Delete backup file after 7 days if no issues: rm users_backup_*.sql

Parallel Development with Git Worktrees - Manual Execution Guide

Date: 2025-12-31 Estimated Time: 10 minutes Difficulty: Easy Corresponding Code Agent Instructions: instructions/instruct-20251231_160000-parallel-worktrees.md

---

Prerequisites

Before starting, ensure:

• [ ] Git 2.15+ installed (worktrees were improved in this version)
• [ ] You're in a git repository
• [ ] All changes are committed or stashed (clean working directory)
• [ ] You know which branches you want to work on

Verify Prerequisites

# Check git version
git --version
# Expected: git version 2.15.0 or higher

# Check you're in a git repo
git rev-parse --is-inside-work-tree
# Expected: true

# Check for clean working directory
git status --porcelain
# Expected: (empty output means clean)

---

Overview

What This Accomplishes

Git worktrees let you have multiple branches checked out simultaneously in different directories. This is useful when you need to:

• Work on two features in parallel
• Compare implementations side-by-side
• Keep a reference copy while making changes
• Run tests on one branch while coding on another

What You'll Do

1. Create worktree directories for each parallel task 2. Set up environment in each worktree 3. Verify everything is working 4. (Later) Clean up when done

---

Step 1: Identify Your Tasks

Why This Step

Before creating worktrees, you need to know what branches you'll work on. Each worktree needs a unique branch name.

Plan Your Worktrees

For this example, we'll create two parallel tasks:

• Task A: JSON import feature → branch feature/json-import
• Task B: Embeddings system → branch feature/embeddings

# Set variables for clarity (adjust for your tasks)
TASK_A_BRANCH="feature/json-import"
TASK_B_BRANCH="feature/embeddings"
PROJECT_ROOT=$(pwd)

echo "Creating worktrees from: $PROJECT_ROOT"
echo "Task A branch: $TASK_A_BRANCH"
echo "Task B branch: $TASK_B_BRANCH"

Expected Output

Creating worktrees from: /Users/you/projects/myapp
Task A branch: feature/json-import
Task B branch: feature/embeddings

---

Step 2: Create Worktree Directories

Why This Step

A worktree is a linked working directory that shares the same .git data but has its own branch checked out. We create them in a .worktrees/ subdirectory to keep them organized.

Commands

# Create directory for worktrees (if it doesn't exist)
mkdir -p .worktrees

# Create worktree for Task A
git worktree add .worktrees/task-a -b $TASK_A_BRANCH main

# Create worktree for Task B
git worktree add .worktrees/task-b -b $TASK_B_BRANCH main

Expected Output

Preparing worktree (new branch 'feature/json-import')
HEAD is now at abc1234 Latest commit on main
Preparing worktree (new branch 'feature/embeddings')
HEAD is now at abc1234 Latest commit on main

Verification

# List all worktrees
git worktree list

Expected:

/Users/you/projects/myapp                     abc1234 [main]
/Users/you/projects/myapp/.worktrees/task-a   abc1234 [feature/json-import]
/Users/you/projects/myapp/.worktrees/task-b   abc1234 [feature/embeddings]

If This Fails

---

Step 3: Copy Environment Files

Why This Step

Worktrees share git data but NOT working files. Your .env, config files, and node_modules won't be present in new worktrees. You need to copy or recreate them.

Commands

# Copy environment files to each worktree
cp .env .worktrees/task-a/ 2>/dev/null || echo "No .env to copy"
cp .env .worktrees/task-b/ 2>/dev/null || echo "No .env to copy"

# If using Node.js, install dependencies in each
# (Run these if applicable to your project)
# cd .worktrees/task-a && npm install && cd -
# cd .worktrees/task-b && npm install && cd -

Expected Output

(no output if successful, or "No .env to copy" if you don't have one)

Verification

# Confirm env files were copied
ls -la .worktrees/task-a/.env .worktrees/task-b/.env 2>/dev/null || echo "No .env files needed"

If This Fails

---

Step 4: Open Worktrees in Separate Terminals

Why This Step

The power of worktrees is working in parallel. Open each worktree in its own terminal (or IDE window) so you can switch between tasks without git operations.

Commands

# Option A: Open in new terminal tabs (macOS)
open -a Terminal .worktrees/task-a
open -a Terminal .worktrees/task-b

# Option B: Print paths to open manually
echo "Task A: cd $PROJECT_ROOT/.worktrees/task-a"
echo "Task B: cd $PROJECT_ROOT/.worktrees/task-b"

Expected Output

Task A: cd /Users/you/projects/myapp/.worktrees/task-a
Task B: cd /Users/you/projects/myapp/.worktrees/task-b

Verification

In each terminal:

# Confirm you're in the right worktree
pwd
git branch --show-current

Expected for Task A:

/Users/you/projects/myapp/.worktrees/task-a
feature/json-import

---

Final Verification

Confirm your worktree setup is complete:

# From the main project directory
git worktree list --porcelain | grep -E "^worktree|^branch"

Expected Final State

---

Working in Worktrees

Now you can work in each worktree independently:

# In Task A terminal
cd .worktrees/task-a
git add . && git commit -m "feat: add JSON import"
git push -u origin feature/json-import

# In Task B terminal (parallel, no conflicts)
cd .worktrees/task-b
git add . && git commit -m "feat: add embeddings"
git push -u origin feature/embeddings

Key benefit: No branch switching, no stashing, no merge conflicts between your parallel work.

---

Cleanup (When Done)

When you're finished with a task and have merged the branch:

# Remove a worktree (from main project directory)
git worktree remove .worktrees/task-a

# Delete the branch if merged
git branch -d feature/json-import

# List remaining worktrees
git worktree list

If Cleanup Fails

---

Summary

---

Next Steps

After setup is complete:

• [ ] Start working on Task A in its terminal
• [ ] Start working on Task B in its terminal
• [ ] Create PRs for each when ready
• [ ] Clean up worktrees after merging

---

Tips

1. Add `.worktrees/` to `.gitignore` - Prevents accidentally committing worktree directories 2. Use descriptive worktree names - task-a is okay, but json-import is clearer 3. Don't nest worktrees - Keep them flat in .worktrees/ 4. Run tests in each - Worktrees are isolated, so tests won't interfere

Human Instruction Examples

This directory contains example human instructions demonstrating the difference between vague summaries (BAD) and executable documentation (GOOD).

Files

Key Principles

Human instructions must be executable documentation, not summaries. Every instruction file should include:

1. Copy-pasteable commands - Exact bash commands, not descriptions 2. Expected output - What success looks like 3. Verification steps - How to confirm each step worked 4. Why explanations - Context for human decision-making 5. Troubleshooting tables - Common errors and solutions

Using These Examples

When creating new human instructions:

1. Start from the template in references/human_instruction_structure.md 2. Use GOOD-database-migration.md or GOOD-parallel-worktrees.md as reference 3. Review BAD-vague-summary.md to avoid common mistakes

Template Quick Reference

## Step N: [Step Name]

### Why This Step
[1-2 sentences explaining purpose]

### Commands

exact-command --with --flags

### Expected Output

What the user should see

### Verification

how-to-verify-success

### If This Fails

| Error | Cause | Solution |
|-------|-------|----------|
| error-message | root-cause | fix-command |

Checklist Before Publishing

• [ ] Can a new team member follow this without asking questions?
• [ ] Are all commands copy-pasteable?
• [ ] Is expected output shown for every command?
• [ ] Are at least 2-3 common errors documented per step?
• [ ] Is there a rollback procedure if something goes wrong?

Architect Agent Guides

This directory contains workflow guides loaded on-demand based on user intent.

Directory Structure

guides/
├── README.md                    # This file
└── workflows/                   # Step-by-step workflow guides
    ├── create-instructions.md   # Creating delegation instructions
    ├── grade-work.md           # Grading code agent work
    ├── send-instructions.md    # Sending instructions to code agent
    └── initialize-workspace.md # Setting up new workspace

Usage

Guides are loaded by the skill's decision tree based on user intent:

Adding New Guides

1. Create markdown file in appropriate subdirectory 2. Include trigger phrase in header 3. Add prerequisite checks 4. Document step-by-step workflow 5. Include quick checklist 6. Update SKILL.md intent classification table

Guide Format

Each guide should follow this structure:

# Workflow: [Name]

**Trigger:** User says "[trigger phrase]"

## Prerequisites
[What must be true before starting]

## Workflow Steps
### 1. First Step
[Details]

### 2. Second Step
[Details]

## Quick Checklist
- [ ] Item 1
- [ ] Item 2

Workflow: Create Instructions

Trigger: User says "write instructions for code agent" or "create instructions"

Prerequisites

Before creating instructions, verify:

# Check architect workspace structure exists
ls -la instructions/ human/ grades/ ticket/

If missing, inform user to initialize workspace first.

Workflow Steps

1. Gather Context

• Review ticket/current_ticket.md for ticket details
• Check analysis/ for any prior research
• Ask clarifying questions if requirements unclear

2. Generate Timestamp

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Example: 20251127_143045

3. Create Technical Instructions

File: instructions/instruct-${TIMESTAMP}-description.md

Structure:

# INSTRUCT: [Clear Title]

**Date:** YYYY-MM-DD
**Ticket:** [TICKET-ID] (if applicable)
**Phase:** [Phase number if multi-phase]

## Context
[Background information code agent needs]

## Objectives
- Primary objective
- Secondary objectives

## Requirements
- Specific technical requirements
- Quality standards to meet

## Constraints
- What NOT to do
- Known limitations
- Gotchas to avoid

## Implementation Steps
1. First step with details
2. Second step with details
3. Continue as needed

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] All tests pass

## Testing Requirements
- Required test types
- Minimum coverage expectations
- Specific test scenarios

## References
- Links to relevant documentation
- Related analysis files

4. Create Human Instructions (Executable Documentation)

File: human/human-${TIMESTAMP}-description.md

CRITICAL: Human instructions are NOT summaries. They must be executable documentation that a human can follow manually when code agents are unavailable.

Load: references/human_instruction_structure.md for the complete template.

Required Elements:

# [Task Name] - Manual Execution Guide

**Date:** YYYY-MM-DD
**Estimated Time:** X minutes
**Difficulty:** Easy | Medium | Advanced
**Corresponding Code Agent Instructions:** instructions/instruct-${TIMESTAMP}-description.md

---

## Prerequisites

Before starting, ensure:
- [ ] [Specific requirement with verification command]

## Overview

### What This Accomplishes
[2-3 sentences explaining the goal and why it matters]

---

## Step 1: [Descriptive Step Name]

### Why This Step
[1-2 sentences explaining purpose - humans benefit from understanding why]

### Commands

Copy-pasteable commands

exact-command --with --flags

### Expected Output

[What success looks like]

### Verification

How to confirm it worked

### If This Fails

| Error | Cause | Solution |
|-------|-------|----------|
| error-message | root-cause | fix-command |

---

[Repeat for each step...]

---

## Final Verification
[How to confirm entire task succeeded]

## Rollback Procedure
[How to undo if something goes wrong]

## Summary
| Step | What You Did | Time |
|------|--------------|------|

Examples: See examples/human-instructions/ for complete examples.

5. Verify Files Match

# Both files should have same timestamp
ls -la instructions/instruct-${TIMESTAMP}-*.md
ls -la human/human-${TIMESTAMP}-*.md

6. Display Human Summary

After creating both files, display the human summary to user for review before sending.

Quick Checklist

• [ ] Ticket context reviewed
• [ ] Technical instructions created in instructions/
• [ ] Human instructions created in human/ (executable, not summary!)
• [ ] Timestamps match between files
• [ ] Success criteria are measurable
• [ ] Testing requirements specified

Human Instruction Checklist

• [ ] Every step has copy-pasteable commands
• [ ] Expected output shown for each command
• [ ] Verification steps provided
• [ ] Troubleshooting table with common errors
• [ ] "Why This Step" explanations included
• [ ] Prerequisites clearly listed
• [ ] Rollback procedure documented

Next Action

After user approves:

• Run "send instructions to code agent"
• Or use /project.send command

Workflow: Grade Completed Work

Trigger: User says "grade the code agent's work" or "evaluate completed work"

Prerequisites

Before grading, verify:

# Check grades directory exists
ls -la grades/

# Verify you have access to code agent logs
ls -la [CODE_AGENT_WORKSPACE]/debugging/logs/

Workflow Steps

1. Locate the Original Instructions

Find the instruction file that corresponds to the work being graded:

ls -lt instructions/instruct-*.md | head -5

Extract the timestamp for the grade file:

TIMESTAMP=$(echo "instruct-20251127_143045-description.md" | grep -oP '\d{8}_\d{6}')

2. Review Code Agent Logs

# Find the log file
ls -lt [CODE_AGENT]/debugging/logs/log_*.md | head -3

# Review the log
cat [CODE_AGENT]/debugging/logs/log_[DATE]-description.md

What to look for:

• Pre-work checklist completed
• Decision types used (decision, rationale, investigation, verification, deviation, milestone)
• Tool calls captured
• Tests run and results
• Blockers encountered and solutions

3. Review Code Changes

cd [CODE_AGENT_WORKSPACE]
git log --oneline -10
git diff HEAD~1

What to verify:

• Changes match instruction requirements
• Code quality standards met
• No unrelated changes

4. Verify Tests

# Run tests in code agent workspace
cd [CODE_AGENT_WORKSPACE]
[TEST_COMMAND]  # e.g., npm test, ./gradlew test, pytest

5. Apply Grading Rubric

Total: 100 points

6. Create Grade File

File: grades/grade-${TIMESTAMP}-description.md

Structure:

# Grade: [Title]

**Date:** YYYY-MM-DD
**Instruction File:** instruct-${TIMESTAMP}-description.md
**Log File:** log_[DATE]-description.md

## Overall Score: XX/100

**Grade Level:** [Excellent/Good/Satisfactory/Needs Improvement/Unacceptable]

## Category Scores

### 1. Instruction Adherence (XX/25)
- [What was done well]
- [What was missed]

### 2. Code Quality (XX/20)
- [Strengths]
- [Issues]

### 3. Testing & Validation (XX/20)
- Test results: [Pass/Fail]
- Coverage: XX%
- [Comments]

### 4. Logging & Traceability (XX/10)
- Pre-work checklist: [Complete/Incomplete]
- Decision types used: [List]
- Hook capture: [Working/Not working]

### 5. Communication & Documentation (XX/15)
- [Documentation quality]
- [Code comments]

### 6. Problem Solving (XX/10)
- [How blockers were handled]
- [Creative solutions]

## Summary

[2-3 sentence summary of overall performance]

## Action Items (if grade < 80)

- [ ] Issue 1 to fix
- [ ] Issue 2 to fix

## Recommendations

[Suggestions for future work]

7. Determine Next Action

If Grade >= 80:

• Mark phase/ticket complete
• Archive instruction, human summary, and grade
• Move to next phase or ticket

If Grade < 80:

• Create new instructions addressing issues
• Reference this grade in new instructions
• Re-execute and re-grade

Grade Levels

Quick Checklist

• [ ] Original instructions located
• [ ] Code agent logs reviewed
• [ ] Code changes verified
• [ ] Tests executed and verified
• [ ] All 6 categories scored
• [ ] Grade file created with matching timestamp
• [ ] Next action determined

Workflow: Initialize Architect Workspace

Trigger: User says "set up architect agent" or "initialize workspace"

Prerequisites

Before initializing, verify directories do NOT already exist:

# Check for existing workspace
if [ -d "instructions" ] || [ -d "grades" ] || [ -d "human" ]; then
    echo "❌ Workspace already exists. Aborting to prevent overwrite."
    exit 1
fi

If directories exist, inform user this appears to be an existing workspace.

Workflow Steps

1. Confirm Code Agent Location

Ask user:

Where is the code agent workspace located?
Example: /Users/user/projects/my-project

Store this path for CLAUDE.md configuration.

2. Create Directory Structure

# Core directories with archives
mkdir -p instructions/archive
mkdir -p human/archive
mkdir -p grades/archive
mkdir -p analysis/archive

# Ticket tracking
mkdir -p ticket/{feature,bug,archive}
touch ticket/current_ticket.md

# Documentation
mkdir -p docs

3. Create CLAUDE.md

Create CLAUDE.md with workspace configuration including:

• Code agent workspace path
• Directory structure reference
• Skill trigger documentation
• File naming conventions

4. Create AGENTS.md (Mirror)

cp CLAUDE.md AGENTS.md

5. Initialize Current Ticket

Create ticket/current_ticket.md with template for tracking work.

6. Display Confirmation

Show user what was created and next steps.

Quick Checklist

• [ ] Code agent workspace path obtained
• [ ] Verified no existing workspace
• [ ] Directory structure created
• [ ] CLAUDE.md created with code agent path
• [ ] AGENTS.md mirrors CLAUDE.md
• [ ] current_ticket.md initialized
• [ ] User informed of next steps

Template Alternative

For faster setup, use the template installer:

cd ~/.claude/skills/architect-agent/templates/
./setup-workspace.sh architect [WORKSPACE_PATH] --code-agent-path [CODE_AGENT_PATH]

Workflow: Send Instructions to Code Agent

Trigger: User says "send instructions to code agent" or "send them"

Prerequisites

Before sending, verify:

1. Instruction file exists in instructions/ 2. Human summary exists in human/ with matching timestamp 3. Code agent workspace path is known

# Find latest instruction
LATEST=$(ls -t instructions/instruct-*.md | head -1)
echo "Latest instruction: $LATEST"

# Extract timestamp
TIMESTAMP=$(echo "$LATEST" | grep -oP '\d{8}_\d{6}')
echo "Timestamp: $TIMESTAMP"

# Verify matching human summary exists
ls human/human-${TIMESTAMP}-*.md

Workflow Steps

1. Display Human Summary

Before copying, show the user what will be sent:

cat human/human-${TIMESTAMP}-*.md

2. Copy Instructions (SIMPLE BASH - No Agent!)

CRITICAL: Use simple bash copy. Do NOT spawn agents or use Task tool for this.

# Copy instruction to code agent
cp "$LATEST" [CODE_AGENT_WORKSPACE]/debugging/instructions/current_instructions.md

# Verify copy succeeded
ls -la [CODE_AGENT_WORKSPACE]/debugging/instructions/current_instructions.md

3. Confirm Success

echo "✅ Instructions sent to code agent"
echo "📍 Location: [CODE_AGENT_WORKSPACE]/debugging/instructions/current_instructions.md"
echo ""
echo "Code agent should now:"
echo "1. Run /log-start to initialize logging"
echo "2. Read current_instructions.md"
echo "3. Execute the instructions"
echo "4. Run /log-complete when done"

Why Keep It Simple

• File copy is trivial - no agent processing needed
• Spawning agents wastes tokens
• Direct bash is faster and more reliable
• Architect stays in control

Common Issues

Issue: Permission Denied

# Check if path exists
ls -la [CODE_AGENT_WORKSPACE]/debugging/instructions/

# If directory missing, create it
mkdir -p [CODE_AGENT_WORKSPACE]/debugging/instructions/

Issue: Can't Find Latest Instruction

# List all instructions by date
ls -lt instructions/instruct-*.md

# Use specific file if needed
cp instructions/instruct-[SPECIFIC].md [CODE_AGENT]/debugging/instructions/current_instructions.md

Issue: Code Agent Workspace Path Unknown

Check your CLAUDE.md for the code agent workspace path. If not configured:

# Add to CLAUDE.md
echo "**Code Agent Workspace:** /path/to/code-agent" >> CLAUDE.md

Quick Checklist

• [ ] Latest instruction file identified
• [ ] Matching human summary verified
• [ ] Human summary displayed to user
• [ ] Instructions copied via bash
• [ ] Copy verified successful
• [ ] User informed of next steps

After Sending

The architect should: 1. Monitor code agent progress (check logs periodically) 2. Be available to answer questions if code agent is blocked 3. Prepare to grade work when code agent completes

Architect Agent Skill

   

Transform Claude Code (or any AI coding assistant) into a specialized architect agent that plans, delegates work to code agents, grades implementations, and maintains quality through iterative improvement.

---

What This Skill Does

Plan -> Delegate -> Grade -> Iterate -> Learn

1. Plan: Create detailed, structured instructions for code agents 2. Delegate: Send instructions to code agents for implementation 3. Grade: Evaluate completed work against objective rubrics (target: 95% or higher) 4. Iterate: Guide improvements until quality threshold met 5. Learn: Update code agent memory with successful patterns

---

Installation

Skilz Universal Installer (Recommended)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer. This skill supports the Agent Skill Standard, which means it works with 14+ coding agents including Claude Code, OpenAI Codex, Cursor, and Gemini.

Install Skilz

pip install skilz

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/architect-agent

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/architect-agent.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/architect-agent

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/architect-agent --project --agent codex

Install from SkillzWave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent codex

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent codex --project

# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent gemini

See skill Listing for installation details for 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more. For the full list of supported platforms, visit:

• SkillzWave Platforms
• skilz-cli GitHub Repository

SkillzWave - Largest Agentic Marketplace for AI Agent Skills | SpillWave - Leaders in AI Agent Development

Manual Installation

Clone directly into your Claude Code skills directory:

git clone https://github.com/SpillwaveSolutions/architect-agent.git ~/.claude/skills/architect-agent

---

Key Features

• Objective Grading - 6-category rubric (100 points total)
• Iterative Improvement - Repeat until 95% or higher quality achieved
• Memory Management - Code agents learn from successes and failures
• Progressive Disclosure - 3-level architecture minimizes context usage
• Cross-Workspace Collaboration - Architect to code agent workflows
• Template Automation - Setup workspaces in less than 5 minutes
• Dual-Mode Logging - Works with Claude Code and OpenCode
• Comprehensive Protocols - 29 reference files covering all scenarios

---

Quick Start

Option 1: Automated Setup (Recommended)

# Navigate to templates
cd ~/.claude/skills/architect-agent/templates/

# Create code agent workspace
./setup-workspace.sh code-agent ~/projects/my-code-agent

# Create architect workspace (optional)
./setup-workspace.sh architect ~/projects/my-architect \
    --code-agent-path ~/projects/my-code-agent

# Verify installation
cd ~/projects/my-code-agent
~/projects/my-architect/verify-workspace.sh

Complete in less than 5 minutes! See references/installation.md for details.

Option 2: Manual Setup

Use skill triggers for step-by-step guidance:

• "This is a new architect agent, help me set it up"
• "Write instructions for code agent"
• "Grade the code agent's work"

---

Core Workflows

1. Instruction Creation

User: "write instructions for implementing JWT authentication"

Architect Agent:
  -> Creates human-readable summary (human/*.md)
  -> Creates detailed technical instructions (instructions/*.md)
  -> Includes logging requirements, testing protocol, success criteria

2. Delegation and Execution

Architect: "send instructions to code agent"
  -> Copies to code-agent/debugging/instructions/<uuid>.md
  -> Generates 10-point summary

Code Agent: "run instructions"
  -> Implements features
  -> Creates detailed logs
  -> Signals: "instructions completed, ready for grading"

3. Grading and Iteration

Architect: "grade the work"
  -> Evaluates against rubric
  -> If 95% or higher: Success! Files deleted
  -> If less than 95%: Creates improvement instruction

Code Agent: "improve your score" (if needed)
  -> Implements targeted fixes
  -> Repeat until 95% or higher

---

Architecture

Three-Level Progressive Disclosure

Level 1: Metadata (~100 words)

• Always in context
• Skill name, description, triggers

Level 2: SKILL.md (less than 5k words)

• Core workflows and protocols
• Quick reference checklists
• Links to detailed references

Level 3: References (unlimited)

• 29 detailed protocol files
• Loaded only when needed
• Keeps context window lean

Multi-Workspace Structure

Architect Workspace           Code Agent Workspace
(YOU work here)                (THEY work there)
===================           ====================
instructions/                 src/
  instruct-*.md <- YOU          code files <- THEY
human/                        tests/
  human-*.md <- YOU             test files <- THEY
grades/                       debugging/
  grade-*.md <- YOU               logs/ <- THEY
ticket/                          instructions/ (temporary)
analysis/                     CLAUDE.md (memory)
CLAUDE.md                     AGENTS.md (protocols)

---

Documentation

Essential Reading

1. [SPEC.md](SPEC.md) - Project specification (purpose, scope, architecture) 2. [SKILL.md](SKILL.md) - Main skill documentation (all triggers and workflows) 3. [references/README.md](references/README.md) - Index of all 29 reference files 4. [CONTRIBUTING.md](CONTRIBUTING.md) - Git workflow and contribution guidelines

Quick Links

Setup and Installation:

• references/installation.md - Complete installation guide
• references/upgrade.md - Migration from v1.0/v2.0 to v3.0+
• references/quick_start.md - 5-minute getting started

Core Protocols:

• references/logging_protocol.md - Real-time logging with tee
• references/testing_protocol.md - Progressive testing schedule
• references/grading_rubrics.md - 6-category grading system
• references/agent_specialization.md - Right agent for the job

Advanced:

• references/instruction_grading_workflow.md - Iterative improvement cycle
• references/permissions_setup_protocol.md - Cross-workspace permissions

OpenCode Integration:

• references/opencode_integration_quickstart.md - Dual-mode setup
• references/claude_vs_opencode_comparison.md - Feature comparison

---

Grading Rubric

Target: 95 points or higher for successful completion

Automatic Grade Caps:

• No unit tests run: Max D (65%)
• Tests fail: F (50%) - UNACCEPTABLE
• Coverage less than 60%: Max C- (70%)

---

Version History

• v4.0 (Current): Comprehensive reorganization, all references linked, seamless UX
• v3.0: Hooks fix (settings.json), automated templates, verification scripts
• v2.0: Hybrid logging, improved protocols
• v1.0: Initial release (manual logging)

---

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for complete workflow.

Quick Summary: 1. Create feature/fix branch (feat/<description> or fix/<description>) 2. Create GitHub issue FIRST 3. Commit with issue reference (Fixes #<number>) 4. Create pull request with full description 5. Never commit directly to main

---

Support and Community

Documentation:

• Browse references/ for detailed protocols
• Read SPEC.md for project architecture
• Check SKILL.md for complete usage guide

Getting Help:

• Review references/get_unstuck_protocol.md for troubleshooting
• Check references/quick_start.md for common questions
• Create an issue for bugs or feature requests

---

License

MIT License - Modify and adapt for your workflow and team needs.

---

Last Updated: 2025-12-29 Version: 4.0

Agent Specialization Protocol

Overview

Learned from TKT-121 Phase 8: Improper agent usage led to incomplete work and grade deductions.

Core Principle: Right Agent for the Job

Each agent has a specific purpose. Do NOT use agents outside their specialization.

Misusing agents results in:

• Incomplete work (documentation agents skipped)
• Wrong tool for the job (qa-enforcer for doc creation)
• Grade deductions (-1 to -2 points per violation)

Agent Categories and Specializations

Validation Agents (Technical Quality)

qa-enforcer - Technical Validation ONLY

Purpose: Test coverage, completeness, success criteria verification

Use for:

• Final validation before marking work complete
• Verifying all success criteria met
• Checking test coverage >= 60%
• Confirming all requirements completed

Do NOT use for:

• Creating documentation
• Writing change logs
• Syncing documentation files
• Generating reports

Make MANDATORY: Always required before completion

Example proper usage:

## Final Validation

Before marking complete:
1. Create completion documentation manually
2. Use change-explainer to analyze changes
3. Use docs-sync-editor to update README.md
4. **Use qa-enforcer to validate all success criteria**

Example improper usage (❌ WRONG):

## Final Validation

Use qa-enforcer to:
- Create the migration summary ❌ (qa-enforcer doesn't create docs)
- Update README.md ❌ (docs-sync-editor does this)
- Validate completion ✅ (correct use)

---

Documentation Agents (Content Creation)

change-explainer - Change Documentation

Purpose: Analyze and document code changes, explain modifications

Use for:

• Creating change logs after significant work
• Explaining what changed and why
• Documenting modifications for team review
• Generating change summaries

Make MANDATORY: After creating significant documentation files

Example use case:

After creating TKT-121-MIGRATION-COMPLETE.md:
1. ✅ Create the document manually
2. ✅ Use change-explainer to analyze all changes in the document
3. ✅ Use change-explainer output to improve the document

When to use:

• After major feature completion
• After migration or refactoring
• After creating completion documentation
• When summarizing a phase's work

docs-sync-editor - Documentation Synchronization

Purpose: Keep documentation in sync with code changes

Use for:

• Updating README.md after code changes
• Syncing CLAUDE.md with new patterns
• Updating API documentation
• Maintaining consistency across docs

Make MANDATORY: When migration or major changes affect project documentation

Example use case:

After completing GCP project migration:
1. ✅ Create migration documentation
2. ✅ Use docs-sync-editor to update README.md with new project references
3. ✅ Use docs-sync-editor to update CLAUDE.md with new patterns

When to use:

• After significant code changes
• After infrastructure changes
• After migration completion
• When README/CLAUDE.md need updates

mermaid-architect - Architecture Diagrams

Purpose: Create visual architecture documentation with Mermaid diagrams

Use for:

• System architecture diagrams
• Data flow visualizations
• Deployment diagrams
• Sequence diagrams

Make OPTIONAL BUT RECOMMENDED: For completion phases, migration documentation

Example use case:

For final migration documentation:
1. ✅ Create text documentation
2. ✅ Use mermaid-architect to generate architecture diagrams
3. ✅ Include diagrams in completion docs

grammar-style-editor - Writing Improvement

Purpose: Improve grammar, clarity, engagement of written content

Use for:

• Polishing user-facing documentation
• Improving README.md readability
• Enhancing PR descriptions
• Refining technical writing

Make OPTIONAL: For final polish of important docs

---

Development Agents (Implementation)

python-expert-engineer - Python Development

Purpose: Python code implementation and architectural review

Use for:

• Complex Python features
• Refactoring Python code
• Design pattern implementation
• Python-specific best practices

Example use case:

For implementing async orchestration:
1. Use python-expert-engineer for architectural guidance
2. Implement based on recommendations
3. Use qa-enforcer for final validation

root-cause-debugger - Debugging

Purpose: Systematic debugging and root cause analysis

Use for:

• When tests fail unexpectedly
• When bugs occur during development
• When encountering unexpected behavior
• When systematic investigation needed

Example use case:

When encountering test failures:
1. Read error message
2. Use root-cause-debugger to investigate
3. Apply recommended fixes
4. Re-run tests

code-quality-reviewer - Code Review

Purpose: Code quality, security, and best practices review

Use for:

• After completing significant code changes
• Before creating PR
• When reviewing refactored code
• Security audits

---

Instructions Templates for Different Phases

Early/Middle Phases (Feature Development)

## Required Agents

**MANDATORY Agents:**
- `qa-enforcer` - Run before marking phase complete

**RECOMMENDED Agents:**
- `root-cause-debugger` - If tests fail or bugs occur
- `python-expert-engineer` - For complex Python implementation

**Completion Checklist:**
- [ ] Feature implemented
- [ ] Tests passing
- [ ] qa-enforcer validation complete

Milestone Phases (Integration Points)

## Required Agents

**MANDATORY Agents:**
- `qa-enforcer` - Final validation
- `change-explainer` - Document changes made in this milestone

**RECOMMENDED Agents:**
- `docs-sync-editor` - If README or API docs affected
- `mermaid-architect` - For architecture changes

**Completion Checklist:**
- [ ] Milestone features complete
- [ ] change-explainer run on changes
- [ ] Documentation updated (if applicable)
- [ ] qa-enforcer validation complete

Final Phases (Completion/Documentation)

## Required Agents

**MANDATORY Agents:**
- `qa-enforcer` - Technical validation ONLY (not for doc creation)
- `change-explainer` - After creating completion docs
- `docs-sync-editor` - Update README.md, CLAUDE.md with project state

**RECOMMENDED Agents:**
- `mermaid-architect` - Create architecture diagrams for completion docs
- `grammar-style-editor` - Polish user-facing documentation

**YOU CANNOT mark this phase complete until:**
- [ ] Completion documentation created manually
- [ ] change-explainer has analyzed all documentation
- [ ] docs-sync-editor has updated README.md and CLAUDE.md
- [ ] qa-enforcer has validated all success criteria

**Completion Checklist:**
- [ ] All code complete
- [ ] Completion docs created
- [ ] change-explainer run
- [ ] README.md updated via docs-sync-editor
- [ ] CLAUDE.md updated via docs-sync-editor
- [ ] Architecture diagrams created (if applicable)
- [ ] User-facing docs polished (if applicable)
- [ ] qa-enforcer final validation complete

Common Mistakes to Avoid

Mistake #1: Using qa-enforcer for Documentation

❌ WRONG:

Run qa-enforcer to create the migration summary and validation report

Problem: qa-enforcer validates technical quality, doesn't create documentation

✅ RIGHT:

1. Create migration summary manually
2. Use change-explainer to analyze and document changes
3. Use docs-sync-editor to update README.md and CLAUDE.md
4. Use qa-enforcer to validate all work is complete

Grade Impact: -2 points for using qa-enforcer incorrectly

---

Mistake #2: Making Documentation Agents "Optional"

❌ WRONG:

**Recommended Agents (Optional but Helpful):**
- change-explainer - Create change documentation
- docs-sync-editor - Keep docs in sync with code changes

Problem: Code agent may skip them, leading to incomplete documentation

✅ RIGHT:

**MANDATORY Agents:**
- qa-enforcer - Technical validation
- change-explainer - MUST use after creating completion docs
- docs-sync-editor - MUST use to update README.md and CLAUDE.md

YOU CANNOT mark this phase complete until:
- change-explainer has analyzed all documentation
- docs-sync-editor has updated README.md and CLAUDE.md
- qa-enforcer has validated all success criteria

Grade Impact: -2 points for making mandatory agents optional

---

Mistake #3: Not Using change-explainer After Doc Creation

❌ WRONG:

1. Create MIGRATION-COMPLETE.md
2. Use qa-enforcer to validate ❌

Problem: Missing analysis and improvement of documentation

✅ RIGHT:

1. Create MIGRATION-COMPLETE.md
2. Use change-explainer to analyze changes
3. Use docs-sync-editor to update README.md
4. Use qa-enforcer to validate completion

Grade Impact: -1 point for skipping change-explainer

---

Mistake #4: Not Using docs-sync-editor for README/CLAUDE.md

❌ WRONG:

1. Complete migration
2. Create completion docs
3. Use qa-enforcer to validate ✅
4. Mark complete ❌ (README.md not updated)

Problem: Project documentation out of sync with reality

✅ RIGHT:

1. Complete migration
2. Create completion docs
3. Use change-explainer to analyze
4. Use docs-sync-editor to update README.md and CLAUDE.md
5. Use qa-enforcer to validate

Grade Impact: -1 point for not updating core docs

Success Criteria Must Include Agent Usage

When creating success criteria for phases, include agent usage:

## Success Criteria (15 required)

**Implementation:**
- [ ] Feature X implemented
- [ ] Tests passing
- [ ] Coverage >= 60%

**Documentation:**
- [ ] Migration summary created
- [ ] change-explainer run on completion docs
- [ ] README.md updated via docs-sync-editor
- [ ] CLAUDE.md updated via docs-sync-editor

**Validation:**
- [ ] qa-enforcer validation complete
- [ ] All tests passing
- [ ] Coverage >= 60%

Grading Impact

Automatic grade deductions for improper agent usage:

Reference Case Study: TKT-121 Phase 8

What Happened

Instructions said:

**Recommended Agents (Optional but Helpful):**
- change-explainer - Create change documentation
- docs-sync-editor - Keep docs in sync with code changes

Code agent did:

• ✅ Used qa-enforcer for validation (correct)
• ✅ Created docs manually (acceptable but less optimal)
• ❌ Did NOT use docs-sync-editor for README.md/CLAUDE.md updates

Result:

• README.md not updated with new GCP project references
• CLAUDE.md not updated with new patterns
• Grade deduction: -2 points

Final Grade: B+ (88%) instead of A (90%+)

What Should Have Happened

Instructions should have said:

**MANDATORY Agents:**
- qa-enforcer - Technical validation
- change-explainer - MUST use after creating completion docs
- docs-sync-editor - MUST use to update README.md and CLAUDE.md

YOU CANNOT mark this phase complete until:
- change-explainer has analyzed all documentation
- docs-sync-editor has updated README.md and CLAUDE.md
- qa-enforcer has validated all success criteria

Code agent would have:

• ✅ Used change-explainer after doc creation
• ✅ Used docs-sync-editor for README/CLAUDE.md
• ✅ Used qa-enforcer for validation
• ✅ All files updated

Result: A (95%) grade - all requirements met

Quick Reference

When to Use Each Agent

Agent Usage Checklist for Instructions

When creating instructions, ask yourself:

• [ ] Is qa-enforcer marked MANDATORY for final validation?
• [ ] Is change-explainer MANDATORY if creating significant docs?
• [ ] Is docs-sync-editor MANDATORY if README/CLAUDE.md affected?
• [ ] Are doc agents NOT being asked to do technical validation?
• [ ] Is qa-enforcer NOT being asked to create documentation?
• [ ] Are success criteria explicit about which agents to use?

Red Flags in Instructions

Watch for these patterns that lead to grade deductions:

🚩 "Use qa-enforcer to create..." (qa-enforcer doesn't create) 🚩 "Recommended (Optional)" for doc agents in final phases (should be mandatory) 🚩 No mention of change-explainer after doc creation (will be skipped) 🚩 No mention of docs-sync-editor when README affected (docs won't sync) 🚩 Success criteria missing agent usage requirements (agents may be skipped)

Key Takeaways

1. qa-enforcer = validation only - Never for creation 2. change-explainer = after doc creation - Mandatory in final phases 3. docs-sync-editor = keep docs in sync - Mandatory when README/CLAUDE.md affected 4. Make it explicit - "Recommended" = optional = may be skipped 5. Success criteria should list agents - Makes requirements crystal clear 6. Wrong agent = wrong results - Each agent has specific expertise

Decision Types for Logging

Version: 1.0 Purpose: Standardized decision type labels for consistent logging across all agents

---

Overview

When code agents log their work, they should categorize entries using these standard decision types. This enables better traceability, grading, and audit trails.

---

Decision Types

1. decision

Purpose: A choice made between alternatives

When to use:

• Selecting between implementation approaches
• Choosing a library or framework
• Picking a design pattern

Format:

**Decision:** [What was decided]
**Alternatives:** [What other options existed]
**Chosen:** [Which option was selected]

Example:

./debugging/scripts/log-decision.sh decision "Use Repository pattern for data access instead of direct database calls"

---

2. rationale

Purpose: Explanation of why a decision was made

When to use:

• Justifying a technical choice
• Explaining trade-offs considered
• Documenting business or technical reasoning

Format:

**Rationale:** [Why this choice was made]
**Benefits:** [Expected positive outcomes]
**Trade-offs:** [What was sacrificed]

Example:

./debugging/scripts/log-decision.sh rationale "Repository pattern chosen for testability - allows mocking data layer in unit tests without database"

---

3. investigation

Purpose: Research or discovery activities

When to use:

• Exploring unfamiliar code
• Debugging to find root cause
• Researching documentation or APIs
• Understanding system behavior

Format:

**Investigation:** [What was being investigated]
**Findings:** [What was discovered]
**Implications:** [What this means for the task]

Example:

./debugging/scripts/log-decision.sh investigation "Traced authentication flow - JWT validation happens in middleware before controller"

---

4. verification

Purpose: Confirming something works as expected

When to use:

• After implementing a feature
• After fixing a bug
• After deployment or configuration change
• Running tests to confirm behavior

Format:

**Verification:** [What was verified]
**Method:** [How it was verified]
**Result:** [Success/Failure + details]

Example:

./debugging/scripts/log-decision.sh verification "API endpoint returns 200 with expected payload after auth header added"

---

5. deviation

Purpose: Documenting departure from instructions or plans

When to use:

• Instructions cannot be followed exactly
• Unexpected circumstances require different approach
• Blockers necessitate workaround

Format:

**Deviation:** [What changed from plan]
**Reason:** [Why the deviation was necessary]
**Impact:** [How this affects outcome]

Example:

./debugging/scripts/log-decision.sh deviation "Used axios instead of fetch - fetch not available in Node 16 environment"

---

6. milestone

Purpose: Marking significant progress points

When to use:

• Completing a major task section
• Achieving a success criterion
• Reaching a checkpoint in multi-step work

Format:

**Milestone:** [What was achieved]
**Progress:** [X of Y steps complete]
**Next:** [What comes next]

Example:

./debugging/scripts/log-decision.sh milestone "Database schema migration complete - 3 of 5 phases done"

---

Quick Reference Table

---

Usage Examples

In Log Files

## 14:32:15 - Investigation
**Investigation:** Checking why tests fail on CI but pass locally
**Findings:** CI uses Node 18, local uses Node 20 - API difference in fetch
**Implications:** Need to polyfill or use axios for compatibility

## 14:45:22 - Decision
**Decision:** Use axios for HTTP requests
**Alternatives:** fetch with polyfill, node-fetch, got
**Chosen:** axios - most stable, works across Node versions

## 14:46:00 - Rationale
**Rationale:** axios has consistent API across environments
**Benefits:** No polyfill needed, better error handling
**Trade-offs:** Additional dependency

## 15:12:45 - Verification
**Verification:** Tests pass on both Node 18 and Node 20
**Method:** Ran `npm test` in both environments
**Result:** ✅ All 47 tests passing

## 15:15:00 - Milestone
**Milestone:** HTTP client migration complete
**Progress:** 2 of 4 tasks complete
**Next:** Update API service layer

---

Grading Impact

Proper use of decision types affects grading:

---

Integration with Scripts

Using log-decision.sh

# Log a decision
./debugging/scripts/log-decision.sh decision "Selected PostgreSQL over MySQL for JSON support"

# Log an investigation
./debugging/scripts/log-decision.sh investigation "Root cause found: connection pool exhaustion"

# Log a verification
./debugging/scripts/log-decision.sh verification "API responds in <100ms after index added"

# Log a milestone
./debugging/scripts/log-decision.sh milestone "Phase 1 complete - core API implemented"

Script Location

The log-decision.sh script should be at:

[CODE_AGENT_WORKSPACE]/debugging/scripts/log-decision.sh

---

Last Updated: 2025-11-27 Version: 1.0

/project.instruct - Review Instruction Summary

Read the most recent instruction file from the instructions/ directory and create a concise 10-25 bullet point summary showing:

Summary Format:

Main Objectives:

• [Key goal 1]
• [Key goal 2]

Key Requirements:

• [Critical requirement 1]
• [Critical requirement 2]

Critical Constraints:

• [Constraint 1]
• [Constraint 2]

Success Criteria:

• [How to verify success 1]
• [How to verify success 2]

Testing Requirements:

• [Test 1]
• [Test 2]

Display this summary to help review what will be sent to the code agent.

/project.run - Run Current Instructions

Read the current instruction file from the architect agent:

cat debugging/instructions/current_instruction.md

Start executing the instructions

Now run the instructions