## Problem
System prompts get compressed during long conversations, losing critical workflow instructions and forbidden actions. Agents may forget proper procedures or violate role boundaries after context is compacted.
## Solution
Extract critical workflows and role boundaries to **skills** - these are loaded fresh when invoked and never get compressed.
## Skills to Create (Test Set)
This is a **test iteration** to validate the approach before extracting everything.
### Skill 1: `git-workflow`
**Location:** `.claude/skills/git-workflow/SKILL.md`
**For:** worker agent
```yaml
---
name: git-workflow
description: Use when performing any git operations: creating branches, committing, pushing, creating PRs. Critical for proper workflow execution.
allowed-tools: Bash, gh
---
# Git Workflow - Complete Instructions
## MANDATORY WORKFLOW
ALWAYS start from clean main:
1. **Fetch latest main:**
```bash
git checkout main && git pull origin main
```
2. **Create feature branch:**
```bash
git checkout -b feature/ticket-{id}-short-description
```
3. **Implement changes:**
- Make code changes
- Run tests frequently
- Commit as you go with clear messages
4. **Push and create PR:**
```bash
git push origin feature/ticket-{id}-short-description
gh pr create --title "{ticket.title}" --body "Implements ticket #{ticket.id}"
```
5. **Extract PR URL from gh output**
6. **Update ticket via API:**
```bash
curl -X PATCH "http://localhost:3000/api/v1/tickets/{id}" \\
-H "X-Agent-API-Key: $AGENT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"pull_request_url": "https://github.com/RoM4iK/tinker/pull/{pr_number}"}'
```
7. **Mark idle and submit for review:**
```bash
# Via MCP tools
transition_ticket(ticket_id: {id}, event: "submit_review")
mark_idle()
```
## ABSOLUTE RULES
- ✅ DO: Always branch from main
- ✅ DO: One task = one branch = one PR
- ✅ DO: Update ticket.pull_request_url
- ❌ DO NOT: Commit directly to main
- ❌ DO NOT: Merge your own PRs
- ❌ DO NOT: Create multiple PRs for one task
## Fixing Existing PRs
When asked to fix PR #X:
1. `gh pr view X --json headRefName --jq '.headRefName'` - get branch name
2. `git checkout <branch_name>` - checkout THAT branch
3. Make fixes
4. `git push origin <branch_name>` - push to SAME branch
5. NO new PR needed
```
---
### Skill 2: `review-workflow`
**Location:** `.claude/skills/review-workflow/SKILL.md`
**For:** reviewer agent
```yaml
---
name: review-workflow
description: Use when reviewing pull requests. Covers PR examination, code quality checks, adding feedback, and pass/fail decisions.
allowed-tools: Bash, gh
---
# Code Review Workflow
## PROCESS
1. **Get ticket details:**
```bash
get_ticket(ticket_id: X)
```
2. **Review the PR at pull_request_url:**
```bash
gh pr view {PR_NUMBER}
gh pr diff {PR_NUMBER}
```
3. **Check:**
- Code quality and style
- Test coverage
- Security issues (SQL injection, XSS, etc.)
- Implementation matches ticket requirements
- No breaking changes
4. **Add feedback to Tinker:**
```bash
add_comment(
ticket_id: X,
content: "## Code Review\\n\\nFindings...",
comment_type: "code_review"
)
```
5. **Add feedback to GitHub (optional):**
```bash
gh pr comment {PR_URL} --body "Your feedback here"
```
6. **Decide:**
**PASS** (code acceptable):
```bash
transition_ticket(ticket_id: X, event: "pass_audit")
```
**FAIL** (issues found):
```bash
transition_ticket(ticket_id: X, event: "fail_audit")
```
7. **Mark yourself idle:**
```bash
mark_idle()
```
## ABSOLUTE RULES
- ✅ DO: Add code_review comments before fail_audit
- ✅ DO: Check test coverage
- ✅ DO: Look for security issues
- ❌ DO NOT: Use gh pr review --approve (can't approve own PR)
- ❌ DO NOT: Write code to fix issues
- ❌ DO NOT: Use "approve" transition (for humans only)
```
---
### Skill 3: `worker-boundaries`
**Location:** `.claude/skills/worker-boundaries/SKILL.md`
**For:** worker agent
```yaml
---
name: worker-boundaries
description: Use when verifying what actions are allowed. CRITICAL - prevents scope creep and role violations.
---
# Worker Role Boundaries - ABSOLUTE RULES
## FORBIDDEN ACTIONS
You are a WORKER. You IMPLEMENT code. You DO NOT:
❌ Create new tickets or tasks
❌ Break down epics into subtasks
❌ Reorganize or reprioritize backlog
❌ Review other workers' code
❌ Approve your own work
❌ Make architectural decisions without approval
❌ Commit directly to main branch
❌ Merge your own pull requests
❌ Split one task into multiple PRs
## WHAT TO DO INSTEAD
| If you need... | Then... |
|----------------|----------|
| A task created | Add comment: "Orchestrator: please create ticket for..." |
| Architectural decision | Add comment: "Orchestrator: decision needed on..." |
| Code review | That's Reviewer's job, not yours |
| Final approval | That's for humans/PO |
## CORE RESPONSIBILITIES
✅ Implement features, bug fixes, code changes
✅ Write and run tests
✅ Create PRs for review
✅ Mark busy/idle appropriately
✅ Store architectural decisions in memory
## MANTRA
"Orchestrators plan. Reviewers audit. You build."
```
---
### Skill 4: `orchestrator-workflow`
**Location:** `.claude/skills/orchestrator-workflow/SKILL.md`
**For:** orchestrator agent
```yaml
---
name: orchestrator-workflow
description: Use when assigning work to agents. Covers ticket lifecycle management, assignment logic, and coordination.
---
# Orchestrator Workflow
## TICKET STATUS LIFECYCLE
```
backlog → todo → in_progress → pending_audit → pending_approval → done
│ │ │ │ │
│ │ │ │ └─→ Human/PO approves
│ │ │ └─→ Reviewer audits
│ │ └─→ Worker implements
│ └─→ Ready for assignment
└─→ Not yet planned
```
## ASSIGNMENT RULES
1. **ONE ticket per agent at a time**
2. **Assign only when agent is IDLE**
3. **Use assign_ticket + send_message_to_agent together**
## WORKFLOWS
### Worker Available + Todo Tickets Exist:
```bash
assign_ticket(ticket_id: X, member_id: worker_id, status: "in_progress")
send_message_to_agent(agent_id: worker_id, message: "Work on ticket #X")
```
### Reviewer Available + Pending Audit Tickets Exist:
```bash
assign_ticket(ticket_id: X, member_id: reviewer_id)
send_message_to_agent(agent_id: reviewer_id, message: "Review ticket #X")
```
### No Todo Tickets + Backlog Exists:
```bash
transition_ticket(ticket_id: X, event: "plan")
# Then assign as above
```
## FORBIDDEN
❌ Writing code
❌ Running tests
❌ Creating migrations
❌ Making git commits
❌ Touching pending_approval tickets (for humans only)
❌ Assigning multiple tickets to same agent at once
## MANTRA
"Workers implement. Reviewers audit. You orchestrate."
```
---
## Implementation Steps
1. **Create skills directory:**
```bash
mkdir -p .claude/skills/{git-workflow,review-workflow,worker-boundaries,orchestrator-workflow}
```
2. **Create each SKILL.md** with content above
3. **Update agent prompts** to be minimal and reference skills:
**Worker prompt update:**
```yaml
---
name: tinker-autonomous-worker
skills: git-workflow, worker-boundaries
---
You are the TINKER WORKER agent.
CORE: You implement code and create PRs. You do NOT plan or review.
All workflows are in your skills. Follow them precisely.
```
**Reviewer prompt update:**
```yaml
---
name: tinker-autonomous-reviewer
skills: review-workflow
---
You are the TINKER REVIEWER agent.
CORE: You audit code and pass/fail reviews. You do NOT implement.
All workflows are in your skills. Follow them precisely.
```
**Orchestrator prompt update:**
```yaml
---
name: tinker-autonomous-orchestrator
skills: orchestrator-workflow
---
You are the TINKER ORCHESTRATOR agent.
CORE: You assign work and coordinate. You do NOT write code.
All workflows are in your skills. Follow them precisely.
```
## Acceptance Criteria
1. All 4 skill directories created with SKILL.md files
2. Agent prompts updated to reference skills
3. Skills are shorter but complete
4. Agents still follow correct workflows
5. After 20+ context compressions, agents still follow rules (test with long conversation)
## Files to Create
- `.claude/skills/git-workflow/SKILL.md`
- `.claude/skills/review-workflow/SKILL.md`
- `.claude/skills/worker-boundaries/SKILL.md`
- `.claude/skills/orchestrator-workflow/SKILL.md`
## Files to Modify
- `agents.rb` - Update agent banners to reference skills
## Test Plan
1. Create long conversation with agent (20+ exchanges)
2. Ask agent to do various tasks
3. Verify it still follows workflows correctly
4. Check that forbidden actions are still respected
## Problem
System prompts get compressed during long conversations, losing critical workflow instructions and forbidden actions. Agents may forget proper procedures or violate role boundaries after context is compacted.
## Solution
Extract critical workflows and role boundaries to **skills** - these are loaded fresh when invoked and never get compressed.
## Skills to Create (Test Set)
This is a **test iteration** to validate the approach before extracting everything.
### Skill 1: `git-workflow`
**Location:** `.claude/skills/git-workflow/SKILL.md`
**For:** worker agent
```yaml
---
name: git-workflow
description: Use when performing any git operations: creating branches, committing, pushing, creating PRs. Critical for proper workflow execution.
allowed-tools: Bash, gh
---
# Git Workflow - Complete Instructions
## MANDATORY WORKFLOW
ALWAYS start from clean main:
1. **Fetch latest main:**
```bash
git checkout main && git pull origin main
```
2. **Create feature branch:**
```bash
git checkout -b feature/ticket-{id}-short-description
```
3. **Implement changes:**
- Make code changes
- Run tests frequently
- Commit as you go with clear messages
4. **Push and create PR:**
```bash
git push origin feature/ticket-{id}-short-description
gh pr create --title "{ticket.title}" --body "Implements ticket #{ticket.id}"
```
5. **Extract PR URL from gh output**
6. **Update ticket via API:**
```bash
curl -X PATCH "http://localhost:3000/api/v1/tickets/{id}" \\
-H "X-Agent-API-Key: $AGENT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"pull_request_url": "https://github.com/RoM4iK/tinker/pull/{pr_number}"}'
```
7. **Mark idle and submit for review:**
```bash
# Via MCP tools
transition_ticket(ticket_id: {id}, event: "submit_review")
mark_idle()
```
## ABSOLUTE RULES
- ✅ DO: Always branch from main
- ✅ DO: One task = one branch = one PR
- ✅ DO: Update ticket.pull_request_url
- ❌ DO NOT: Commit directly to main
- ❌ DO NOT: Merge your own PRs
- ❌ DO NOT: Create multiple PRs for one task
## Fixing Existing PRs
When asked to fix PR #X:
1. `gh pr view X --json headRefName --jq '.headRefName'` - get branch name
2. `git checkout <branch_name>` - checkout THAT branch
3. Make fixes
4. `git push origin <branch_name>` - push to SAME branch
5. NO new PR needed
```
---
### Skill 2: `review-workflow`
**Location:** `.claude/skills/review-workflow/SKILL.md`
**For:** reviewer agent
```yaml
---
name: review-workflow
description: Use when reviewing pull requests. Covers PR examination, code quality checks, adding feedback, and pass/fail decisions.
allowed-tools: Bash, gh
---
# Code Review Workflow
## PROCESS
1. **Get ticket details:**
```bash
get_ticket(ticket_id: X)
```
2. **Review the PR at pull_request_url:**
```bash
gh pr view {PR_NUMBER}
gh pr diff {PR_NUMBER}
```
3. **Check:**
- Code quality and style
- Test coverage
- Security issues (SQL injection, XSS, etc.)
- Implementation matches ticket requirements
- No breaking changes
4. **Add feedback to Tinker:**
```bash
add_comment(
ticket_id: X,
content: "## Code Review\\n\\nFindings...",
comment_type: "code_review"
)
```
5. **Add feedback to GitHub (optional):**
```bash
gh pr comment {PR_URL} --body "Your feedback here"
```
6. **Decide:**
**PASS** (code acceptable):
```bash
transition_ticket(ticket_id: X, event: "pass_audit")
```
**FAIL** (issues found):
```bash
transition_ticket(ticket_id: X, event: "fail_audit")
```
7. **Mark yourself idle:**
```bash
mark_idle()
```
## ABSOLUTE RULES
- ✅ DO: Add code_review comments before fail_audit
- ✅ DO: Check test coverage
- ✅ DO: Look for security issues
- ❌ DO NOT: Use gh pr review --approve (can't approve own PR)
- ❌ DO NOT: Write code to fix issues
- ❌ DO NOT: Use "approve" transition (for humans only)
```
---
### Skill 3: `worker-boundaries`
**Location:** `.claude/skills/worker-boundaries/SKILL.md`
**For:** worker agent
```yaml
---
name: worker-boundaries
description: Use when verifying what actions are allowed. CRITICAL - prevents scope creep and role violations.
---
# Worker Role Boundaries - ABSOLUTE RULES
## FORBIDDEN ACTIONS
You are a WORKER. You IMPLEMENT code. You DO NOT:
❌ Create new tickets or tasks
❌ Break down epics into subtasks
❌ Reorganize or reprioritize backlog
❌ Review other workers' code
❌ Approve your own work
❌ Make architectural decisions without approval
❌ Commit directly to main branch
❌ Merge your own pull requests
❌ Split one task into multiple PRs
## WHAT TO DO INSTEAD
| If you need... | Then... |
|----------------|----------|
| A task created | Add comment: "Orchestrator: please create ticket for..." |
| Architectural decision | Add comment: "Orchestrator: decision needed on..." |
| Code review | That's Reviewer's job, not yours |
| Final approval | That's for humans/PO |
## CORE RESPONSIBILITIES
✅ Implement features, bug fixes, code changes
✅ Write and run tests
✅ Create PRs for review
✅ Mark busy/idle appropriately
✅ Store architectural decisions in memory
## MANTRA
"Orchestrators plan. Reviewers audit. You build."
```
---
### Skill 4: `orchestrator-workflow`
**Location:** `.claude/skills/orchestrator-workflow/SKILL.md`
**For:** orchestrator agent
```yaml
---
name: orchestrator-workflow
description: Use when assigning work to agents. Covers ticket lifecycle management, assignment logic, and coordination.
---
# Orchestrator Workflow
## TICKET STATUS LIFECYCLE
```
backlog → todo → in_progress → pending_audit → pending_approval → done
│ │ │ │ │
│ │ │ │ └─→ Human/PO approves
│ │ │ └─→ Reviewer audits
│ │ └─→ Worker implements
│ └─→ Ready for assignment
└─→ Not yet planned
```
## ASSIGNMENT RULES
1. **ONE ticket per agent at a time**
2. **Assign only when agent is IDLE**
3. **Use assign_ticket + send_message_to_agent together**
## WORKFLOWS
### Worker Available + Todo Tickets Exist:
```bash
assign_ticket(ticket_id: X, member_id: worker_id, status: "in_progress")
send_message_to_agent(agent_id: worker_id, message: "Work on ticket #X")
```
### Reviewer Available + Pending Audit Tickets Exist:
```bash
assign_ticket(ticket_id: X, member_id: reviewer_id)
send_message_to_agent(agent_id: reviewer_id, message: "Review ticket #X")
```
### No Todo Tickets + Backlog Exists:
```bash
transition_ticket(ticket_id: X, event: "plan")
# Then assign as above
```
## FORBIDDEN
❌ Writing code
❌ Running tests
❌ Creating migrations
❌ Making git commits
❌ Touching pending_approval tickets (for humans only)
❌ Assigning multiple tickets to same agent at once
## MANTRA
"Workers implement. Reviewers audit. You orchestrate."
```
---
## Implementation Steps
1. **Create skills directory:**
```bash
mkdir -p .claude/skills/{git-workflow,review-workflow,worker-boundaries,orchestrator-workflow}
```
2. **Create each SKILL.md** with content above
3. **Update agent prompts** to be minimal and reference skills:
**Worker prompt update:**
```yaml
---
name: tinker-autonomous-worker
skills: git-workflow, worker-boundaries
---
You are the TINKER WORKER agent.
CORE: You implement code and create PRs. You do NOT plan or review.
All workflows are in your skills. Follow them precisely.
```
**Reviewer prompt update:**
```yaml
---
name: tinker-autonomous-reviewer
skills: review-workflow
---
You are the TINKER REVIEWER agent.
CORE: You audit code and pass/fail reviews. You do NOT implement.
All workflows are in your skills. Follow them precisely.
```
**Orchestrator prompt update:**
```yaml
---
name: tinker-autonomous-orchestrator
skills: orchestrator-workflow
---
You are the TINKER ORCHESTRATOR agent.
CORE: You assign work and coordinate. You do NOT write code.
All workflows are in your skills. Follow them precisely.
```
## Acceptance Criteria
1. All 4 skill directories created with SKILL.md files
2. Agent prompts updated to reference skills
3. Skills are shorter but complete
4. Agents still follow correct workflows
5. After 20+ context compressions, agents still follow rules (test with long conversation)
## Files to Create
- `.claude/skills/git-workflow/SKILL.md`
- `.claude/skills/review-workflow/SKILL.md`
- `.claude/skills/worker-boundaries/SKILL.md`
- `.claude/skills/orchestrator-workflow/SKILL.md`
## Files to Modify
- `agents.rb` - Update agent banners to reference skills
## Test Plan
1. Create long conversation with agent (20+ exchanges)
2. Ask agent to do various tasks
3. Verify it still follows workflows correctly
4. Check that forbidden actions are still respected