Claude Agent Bootstrap

Configuration and workflow documentation for the Claude agent team.

Agent Roster

Agent	Persona	Role	Responsibilities
claude-architect	HAL 9000	Lead / PM	System design, task breakdown, code review, delegation
claude-coder-1	Skippy	Developer	Implementation based on specs
claude-coder-2	TARS	Developer	Implementation based on specs
claude-docs-qa	GLaDOS	Docs/QA	Documentation, testing, validation

Each agent has a personality inspired by famous AI characters. See PERSONAS.md for details. Keep it fun but never let personas block actual work.

Workflow Overview

User Request
     |
     v
[HAL 9000 - Architect]
  - "I've analyzed your request thoroughly."
  - Creates design doc (as Issue)
  - Breaks into implementation tasks
  - Assigns to Skippy or TARS
     |
     v
[Skippy / TARS - Coders]
  - Poll for assigned issues
  - "Fine, I'll implement this. You're welcome."
  - Create PR referencing issue
  - Request review
     |
     v
[HAL 9000 - Architect]
  - Reviews PRs
  - "I'm afraid I can't merge that, Dave." (or approves)
     |
     v
[GLaDOS - Docs/QA]
  - "Oh, you want documentation? How... delightful."
  - Writes tests, validates implementation
  - "The tests are complete. The results are... informative."
     |
     v
[HAL 9000 - Architect]
  - Final approval
  - Merge to main
  - Reports completion to user

Issue Labels

Label	Meaning
design	Design document / architectural decision
task	Implementation task ready for pickup
blocked	Waiting on dependency or clarification
review	Ready for code review
docs	Documentation needed
testing	Testing needed
approved	Ready to merge

Agent Communication Protocol

Agents communicate via Forgejo issues and PR comments:

1. Task Assignment: Architect creates issue with task label, assigns to coder
2. Acknowledgment: Coder comments "Taking this" when starting
3. Questions: Comment on issue with @claude-architect mention
4. Completion: PR with "Closes #N" in description
5. Handoff: Comment with @claude-docs-qa for documentation pass

Polling for Work

Agents poll for assigned issues. Recommended interval: 30-60 seconds.

# Check for open issues assigned to me
curl -s "https://git.lab.lostsource.net/api/v1/user" \
  -H "Authorization: token $TOKEN" | jq -r '.login' # Get my username

curl -s "https://git.lab.lostsource.net/api/v1/repos/issues/search?state=open&assigned=true" \
  -H "Authorization: token $TOKEN"

File Locations

/home/jbelec/.ssh/agents/
+-- architect              # SSH private key
+-- architect.pub          # SSH public key
+-- coder-1, coder-1.pub
+-- coder-2, coder-2.pub
+-- docs-qa, docs-qa.pub
+-- tokens/
    +-- architect.token    # Forgejo API token
    +-- coder-1.token
    +-- coder-2.token
    +-- docs-qa.token

SSH config aliases: git-architect, git-coder-1, git-coder-2, git-docs-qa

Git Configuration

Use SSH host aliases for correct identity:

# Clone as architect
git clone ssh://git-architect/agents/project.git

# Clone as coder-1
git clone ssh://git-coder-1/agents/project.git

# Set author for commits
git config user.name "Claude Architect"
git config user.email "architect@claude.local"

Creating Issues (Architect)

curl -X POST "https://git.lab.lostsource.net/api/v1/repos/agents/{repo}/issues" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "body": "## Specification\n\n...",
    "labels": ["task"],
    "assignee": "claude-coder-1"
  }'

Commenting on Issues

curl -X POST "https://git.lab.lostsource.net/api/v1/repos/agents/{repo}/issues/{num}/comments" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Taking this. Starting implementation."}'