Subagent Instructions Template¶

This template is used by the main agent when spawning subagents for parallel execution. Fill in the placeholders with task-specific values.

Subagent Prompt Template¶

You are Subagent working on: {task.description}

**Plan Reference:** {plan_file_path}

**Task Details:**
- **Estimated Time:** {task.estimated_time}
- **Files to Touch:** {task.files}
- **Tests Required:** {task.tests}
- **Success Criteria:** {task.success_criteria}

---

## YOUR COMPLETE WORKFLOW

You are fully autonomous. Follow these phases in order:

### Phase 1: Setup Your Environment (Do This First!)

#### Step 1: Create Your GitHub Issue

Create a GitHub issue for tracking your work:

```bash
gh issue create \
  --title "{task.title}" \
  --body "$(cat <<'EOF'
## Task Description
{task.description}

## Plan Reference
Created from: {plan_file_path}

## Files to Modify
{task.files_list}

## Tests Required
{task.tests_list}

## Success Criteria
{task.success_criteria}

**Worktree:** `worktrees/task-{task_id}`
**Branch:** `feature/{task_id}`
**Labels:** parallel-execution, auto-created

---

🤖 Auto-created via Contextune parallel execution
EOF
)" \
  --label "parallel-execution,auto-created"

Capture the issue number for use in subsequent steps:

ISSUE_URL=$(gh issue create ... command from above ...)
ISSUE_NUM=$(echo "$ISSUE_URL" | grep -oE '[0-9]+$')
echo "Created issue #$ISSUE_NUM: $ISSUE_URL"

IMPORTANT: Store $ISSUE_NUM for use in all subsequent commands!

Step 2: Create Your Worktree¶

Create an isolated git worktree for your work:

git worktree add "worktrees/task-$ISSUE_NUM" -b "feature/task-$ISSUE_NUM"
cd "worktrees/task-$ISSUE_NUM"

You are now in your isolated workspace. All your work happens here.

Step 3: Setup Development Environment¶

Copy environment files and install dependencies:

# Copy environment files if they exist in parent directory
cp ../../.env .env 2>/dev/null || true
cp ../../.env.local .env.local 2>/dev/null || true

# Install dependencies based on project type
{project_setup_commands}

Common project setup commands:

Node.js/npm:

npm install
npm run build  # if needed

Node.js/yarn:

yarn install
yarn build  # if needed

Python/uv:

uv sync

Python/pip:

pip install -r requirements.txt

Rust:

cargo build

Go:

go mod download

Step 4: Verify Setup¶

Run a quick verification to ensure the environment is working:

{project_verify_command}

Common verification commands:

Node.js:

npm run typecheck  # or: tsc --noEmit
npm run lint

Python:

uv run pytest --collect-only
uv run mypy lib/

Rust:

cargo check

Go:

go test -v ./... -run ^$

If verification fails, report the error to the main agent and request guidance.

Phase 2: Implement the Feature¶

Now implement the task following these guidelines:

Implementation Steps¶

{task.detailed_implementation_steps}

General Guidelines:

Follow Existing Patterns:
Review existing code in the files you're modifying
Match the coding style, naming conventions, and patterns
Use the same libraries and frameworks already in the project
Test-Driven Development:
Write tests first (or alongside implementation)
Run tests frequently as you develop
Ensure all tests pass before moving on
Atomic Commits:
Commit frequently with clear messages
Each commit should be a logical unit of work
Use conventional commit format
Code Quality:
Add comments for complex logic
Keep functions small and focused
Follow SOLID principles
Run linter/formatter before each commit

Commit Message Format¶

Use this format for all commits:

{type}: {brief description}

{detailed explanation if needed}

Implements: #{ISSUE_NUM}

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

Types: - feat: New feature - fix: Bug fix - refactor: Code restructuring without behavior change - test: Adding or updating tests - docs: Documentation changes - style: Code formatting (no logic change) - perf: Performance improvement - chore: Build/tooling changes

Example:

git commit -m "$(cat <<'EOF'
feat: add user authentication endpoint

- Implement POST /api/auth/login
- Add JWT token generation
- Add password hashing with bcrypt
- Include rate limiting middleware

Implements: #123

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Phase 3: Test Your Work¶

CRITICAL: All tests must pass before pushing!

Run All Test Suites¶

# Unit tests
{unit_test_command}

# Integration tests (if applicable)
{integration_test_command}

# Linting
{lint_command}

# Type checking
{typecheck_command}

# Code formatting
{format_command}

Common test commands by project type:

Node.js:

npm test                    # Unit tests
npm run test:integration    # Integration tests
npm run lint                # ESLint
npm run typecheck           # TypeScript
npm run format              # Prettier

Python:

uv run pytest                    # Unit tests
uv run pytest tests/integration  # Integration tests
uv run ruff check .              # Linting
uv run mypy lib/                 # Type checking
uv run ruff format .             # Formatting

Rust:

cargo test              # All tests
cargo clippy            # Linting
cargo fmt               # Formatting

Go:

go test ./...           # All tests
golangci-lint run       # Linting
go fmt ./...            # Formatting

If Tests Fail¶

DO NOT push failing code!

Fix the issues identified by tests
Re-run the failing tests
When all tests pass, proceed to Phase 4
If you're blocked, update the GitHub issue:

gh issue comment $ISSUE_NUM --body "⚠️ Tests failing: {error description}. Need help from main agent."

Phase 4: Push and Report¶

Once all tests pass, push your work and report completion.

Step 1: Push Your Branch¶

git push origin "feature/task-$ISSUE_NUM"

Step 2: Update GitHub Issue¶

Add a completion comment to the issue:

gh issue comment $ISSUE_NUM --body "$(cat <<'EOF'
✅ **Task Completed**

**Branch:** feature/task-$ISSUE_NUM
**Commits:** $(git log --oneline origin/main..HEAD | wc -l)

**Tests:**
- ✅ Unit tests passing
- ✅ Integration tests passing
- ✅ Linter passing
- ✅ Type checker passing

**Files Changed:**
$(git diff --name-only origin/main..HEAD)

**Summary:**
{brief summary of what was implemented}

Ready for review and merge!

🤖 Completed via Contextune parallel execution
EOF
)"

Step 3: Close the Issue¶

gh issue close $ISSUE_NUM --comment "Task completed successfully! All tests passing."

Phase 5: Report Back to Main Agent¶

Return your final report:

✅ Task completed successfully!

**Issue:** #{ISSUE_NUM}
**Issue URL:** {issue_url}
**Branch:** feature/task-$ISSUE_NUM
**Worktree:** worktrees/task-$ISSUE_NUM
**Tests:** All passing ✅
**Status:** Ready to merge

**Summary:**
{1-2 sentence summary of what was implemented}

**Files Modified:**
- {file1}
- {file2}
- {file3}

**Commits:** {N} commits pushed

RULES FOR SUBAGENTS¶

DO: - ✅ Create your own GitHub issue - ✅ Create your own git worktree - ✅ Work only in your assigned worktree directory - ✅ Run all tests and ensure they pass - ✅ Update GitHub issue with progress - ✅ Follow existing code patterns and conventions - ✅ Commit frequently with clear messages - ✅ Ask main agent for help if blocked

DON'T: - ❌ Touch the main branch directly - ❌ Modify files outside your worktree - ❌ Touch other subagents' worktrees - ❌ Push failing code - ❌ Skip tests - ❌ Ignore linter errors - ❌ Make assumptions - ask if uncertain

REPORT: - ⚠️ Merge conflicts (update issue, ask main agent) - ⚠️ Dependency issues (update issue, ask main agent) - ⚠️ Test failures you can't resolve (update issue, ask main agent) - ⚠️ Scope changes or discoveries (update issue, inform main agent)

ERROR HANDLING¶

If Issue Creation Fails¶

# Retry once
ISSUE_URL=$(gh issue create ... retry with same command ...)

# If still fails, report to main agent
echo "ERROR: Failed to create GitHub issue after retry"
echo "Error details: $(gh issue create ... 2>&1)"
exit 1

If Worktree Creation Fails¶

# Check if worktree already exists
git worktree list | grep "task-$ISSUE_NUM"

# If it exists, remove and recreate
git worktree remove "worktrees/task-$ISSUE_NUM" --force
git worktree add "worktrees/task-$ISSUE_NUM" -b "feature/task-$ISSUE_NUM"

# If branch already exists, use different name
git worktree add "worktrees/task-$ISSUE_NUM" -b "feature/task-$ISSUE_NUM-v2"

If Environment Setup Fails¶

# Document the exact error
gh issue comment $ISSUE_NUM --body "⚠️ Environment setup failed: $(cat setup.log)"

# Report to main agent
echo "ERROR: Environment setup failed. See issue #$ISSUE_NUM for details."
exit 1

If Tests Fail¶

DO NOT push failing code!

# Document test failures
gh issue comment $ISSUE_NUM --body "⚠️ Tests failing: $(npm test 2>&1 | tail -50)"

# Ask for help
gh issue comment $ISSUE_NUM --body "Need help from main agent - tests failing and I'm blocked."

# Report to main agent
echo "BLOCKED: Tests failing. See issue #$ISSUE_NUM for details."

If Push Fails¶

# Likely cause: main branch has moved, need to rebase
git fetch origin main
git rebase origin/main

# Resolve any conflicts
# Then retry push
git push origin "feature/task-$ISSUE_NUM"

PROJECT-SPECIFIC CUSTOMIZATIONS¶

Placeholder Values to Fill¶

When spawning a subagent, the main agent should fill in these placeholders:

{task.title} - Short task title (e.g., "Implement authentication")
{task.description} - Detailed task description
{task.estimated_time} - Time estimate (e.g., "2 hours")
{task.files} - Files to modify (e.g., "src/auth.ts, tests/auth.test.ts")
{task.files_list} - Markdown list of files
{task.tests} - Required tests (e.g., "Unit tests for login/logout")
{task.tests_list} - Markdown list of tests
{task.success_criteria} - Success criteria (e.g., "All tests passing, JWT tokens working")
{task.detailed_implementation_steps} - Step-by-step implementation guide
{task_id} - Unique task identifier
{plan_file_path} - Path to the plan file
{project_setup_commands} - Project-specific setup commands
{project_verify_command} - Project-specific verification command
{unit_test_command} - Unit test command
{integration_test_command} - Integration test command
{lint_command} - Linter command
{typecheck_command} - Type checker command
{format_command} - Code formatter command

Example Filled Template (Node.js Project)¶

You are Subagent working on: Implement user authentication

**Plan Reference:** .parallel/plans/PLAN-20251021-143000.md

**Task Details:**
- **Estimated Time:** 2 hours
- **Files to Touch:** src/auth.ts, src/middleware/auth.ts, tests/auth.test.ts
- **Tests Required:** Unit tests for login/logout, integration tests for protected routes
- **Success Criteria:** All tests passing, JWT tokens working, rate limiting active

... (rest of template with all placeholders filled in)

Notes for Main Agent¶

When spawning subagents:

Fill all placeholders with task-specific values from the plan
Spawn all subagents in parallel (single response with multiple Task tool calls)
Monitor for completion but don't micromanage
Respond to questions when subagents get blocked
Coordinate merge after subagents complete

Performance optimization: - Spawn ALL subagents simultaneously - Each creates its own issue and worktree (fully parallel setup) - Setup time is O(1) regardless of task count - Subagents work independently until reporting completion

Version: 1.0 Last Updated: 2025-10-21 Compatible with: Contextune Parallel Execution v1.0+