How to Create Task Files

This guide shows you how to create task files for different scenarios.

Basic Task File

Create a simple task without parameters:

# Code Review Task

Please review the code changes with focus on:
- Code quality
- Test coverage
- Security implications

Save as .agents/tasks/code-review.md.

Use with:

coding-context code-review

Task with Parameters

Create a task that accepts dynamic values:

# Feature Implementation: ${feature_name}

Implement the following feature: ${feature_name}

## Requirements
- ${requirements}

## Success Criteria
- ${success_criteria}

Use with:

coding-context \
  -p feature_name="User Authentication" \
  -p requirements="OAuth2 support, secure password storage" \
  -p success_criteria="All tests pass, security audit clean" \
  implement-feature

Multiple Tasks with Selectors

Create multiple variations of the same task using selectors:

For staging environment (.agents/tasks/deploy-staging.md):

---
environment: staging
---
# Deploy to Staging

Deploy with extra validation and monitoring.

For production environment (.agents/tasks/deploy-production.md):

---
environment: production
---
# Deploy to Production

Deploy with all safety checks and rollback plan.

Use with:

# Deploy to staging
coding-context -s environment=staging deploy

# Deploy to production
coding-context -s environment=production deploy

Resume Mode Tasks

Create separate tasks for initial and resume sessions:

Initial task (.agents/tasks/refactor-initial.md):

---
resume: false
---
# Refactoring Task

Analyze the code and create a refactoring plan.

Resume task (.agents/tasks/refactor-resume.md):

---
resume: true
---
# Continue Refactoring

Continue with the refactoring work from your previous session.

Use with:

# Initial session
coding-context -s resume=false refactor

# Resume session (uses -r flag to skip rules and select resume task)
coding-context -r refactor

Tasks with Embedded Selectors

Instead of requiring -s flags on every invocation, you can embed selectors directly in the task frontmatter. This is useful for tasks that always need specific rules.

Example (.agents/tasks/implement-go-feature.md):

---
selectors:
  languages: go
  stage: implementation
---
# Implement Feature in Go

Implement the feature following Go best practices and implementation guidelines.

Feature name: ${feature_name}
Requirements: ${requirements}

Usage:

# Automatically applies languages=go and stage=implementation selectors
coding-context -p feature_name="User Auth" implement-feature

Example with OR logic using arrays:

---
selectors:
  languages: [go, python]
  stage: testing
---
# Write Tests

Write comprehensive tests for the code.

This matches rules where (languages=go OR languages=python) AND stage=testing.

Combining embedded and command-line selectors:

# Task has: selectors.languages = go
# Command adds: -s priority=high
# Result: Includes rules matching languages=go AND priority=high
coding-context -s priority=high implement-feature

Note: Language values should be lowercase (e.g., go, python, javascript).

Task Frontmatter

Task frontmatter is used for filtering and metadata purposes but is NOT included in the output. The frontmatter controls behavior (like auto-filtering rules via the selectors field) but only the task content below the frontmatter delimiters is included in the assembled context.

Example:

coding-context implement-feature

Output (frontmatter NOT included):

# Implement Feature in Go
...

The frontmatter (with selectors, languages, etc.) is parsed and used to filter rules and control behavior, but it does not appear in the final output sent to the AI agent.

Best Practices

  1. Use descriptive task names: Make them clear and specific
  2. Include clear instructions: Be explicit about what the AI should do
  3. Use parameters for dynamic content: Don’t hardcode values that change
  4. Organize by purpose: Keep related tasks together
  5. Document your tasks: Add comments explaining complex requirements

See Also