I wanted to share a pattern I've been developing with Claude while working on a multi-repo project with SpecKit. It's been helpful for dealing with context issues during long development sessions. I kept running into the same issues when working on tasks that would slowly degrade over time, not paying attention to previous instructions, configurations, patterns, etc. I'd like feedback on this as it's been a learning curve.

Claude wouldn't engage the MCPs and sub-agents it was supposed to use, would lose track of which repo it was working in, and would forget what security checks were non-negotiable. The context would slowly degrade over time with each compact, and I'd find myself constantly having to remind it "hey, you need to use the semgrep MCP for this" or "don't forget to invoke the database-expert skill."

Even after I'd remind Claude it would drift back to old patterns. I get it that speckit is LLM agnostic, and I am currently only using Claude, but I imagine this would apply to other platforms and their available feature sets.

What I needed was a way to say: "For THIS specific task, in THIS specific repo, you MUST use THESE specific tools, in THIS specific order." As a requirement.

What I came up with was I started experimenting with creating task-specific instruction files that sit alongside my SpecKit task definitions. The structure looks like this:

project-meta/docs/specs/task-instructions/
├── TEMPLATE.md
├── task-0.2.1-postgres-setup.md
├── task-0.2.2-redis-setup.md
└── task-0.3.1-auth-integration.md

Each file is basically a detailed playbook for that one task. How I implement this currently, is that ask claude to analyze each task in the speckit on which which sub-agents, skills, mcps, etc are that I have loaded and then using the template, create the specific task instructions and then modify the tasks.md to reference the specific intructions for that task. Yes, this eats up more tokens, but it keeps Claude focused so that I am spending less time troubleshooting and going back to do things over.

What Goes In These Files

I've iterated on this template, and still experimenting but I wanted to share to make sure I am not completely off base with this approach:

Task classification tags - I tag each task with types like [DATABASE], [SECURITY-CRITICAL], [API], etc. This should automatically tell Claude which tools are non-negotiable. For example, anything tagged [SECURITY-CRITICAL] MUST run semgrep before completion. No exceptions.

Explicit tool requirements - I list out every MCP, skill, and sub-agent that needs to be used as requirements. Like "you MUST use prisma-local MCP for migrations" or "you MUST invoke the database-expert skill before modifying the schema."

Dependency mapping - Visual maps showing which tasks need to be done first, which ones this task blocks, and which ones can be worked on in parallel.

Workflow sequences - Step-by-step instructions for BEFORE/DURING/AFTER the work. Query memory MCP first, invoke the project skill, research patterns, then start coding. During implementation, use specific tools at specific times. After completion, store decisions and update task status.

Acceptance criteria with teeth - Every task has a checklist that MUST be completed. All items checked off, all quality gates passed, all security scans clean. Can't mark the task complete until everything's done.

What this looks like in practice:

For a security-critical auth task, I'd tag it [SECURITY-CRITICAL] and [AUTHENTICATION], which automatically means:

• Must use semgrep MCP (scan before commit)
• Must use authentication-specialist agent
• Must use nextjs-security-expert agent
• Quality gates include: all auth endpoints scanned, CSRF protection verified, session management reviewed

Claude can't check off the acceptance criteria unless those scans have run.

For a database task, I'd tag it [DATABASE], which means:

• Must use prisma-local MCP for migrations
• Must invoke database-expert skill for RLS patterns
• Must use prisma-supabase-rls-expert agent

Plus I'd map out the dependencies. Like "you can't start this until Task 0.2.1 (PostgreSQL setup) is done, and Tasks 1.2.1 and 1.3.2 are blocked until you finish this."

For long-running sessions, the workflow keeps Claude on track:

• BEFORE: Query memory MCP → Invoke project skill → Research patterns
• DURING: Follow code patterns → Run security scans
• AFTER: Store decisions → Update task status → Commit

Because of this task-scoped context, instead of trying to keep 35 tasks worth of information in Claude's head at once, each task gets its own focused instruction set. When you're working on Redis setup, you only need to think about Redis setup.

And the mandatory tool declarations prevent regression. Claude can look at the file and go "oh right, this is a [DATABASE] task, I need to use these specific tools."

The dependency maps are helpful for multi-repo work too. Claude doesn't get confused about which repo it's in or what order things need to happen plus it's a nice visual for the developer to understand things

How It Plays Out in Practice

Here's a typical workflow now:

Me: "Start working on task 0.3.1"

Claude:

1. Reads the task-0.3.1-auth.md file
2. Sees it's tagged [AUTHENTICATION], [SECURITY-CRITICAL]
3. Queries memory MCP for past authentication decisions
4. Invokes the project-dev skill to load patterns
5. Checks git status in the right repo
6. Verifies prerequisite tasks are actually done
7. Uses the authentication-specialist agent for implementation
8. Runs semgrep scan before marking complete
9. Stores new decisions in memory MCP
10. Updates speckit.tasks.md to show ✅ COMPLETE

The Template Itself

I've sanitized a version of my template that anyone can use. It's got all the placeholders for task metadata, tool requirements, dependencies, acceptance criteria, verification steps, etc. You can grab it and customize it for your own project.

Sanitized Template

# Task {TASK_ID}: {TASK_NAME}

> 📌 This file keeps Claude on track by explicitly listing required tools and workflows for this specific task.

---

## Task Info

| What | Value |
|------|-------|
| **Task ID** | {TASK_ID} (e.g., 0.2.2) |
| **Task Name** | {TASK_NAME} |
| **Phase** | Phase {PHASE_NUMBER}: {PHASE_NAME} |
| **Repository** | {REPOSITORY} (e.g., [WEB]/[API]/[DB]/[WORKER]) |
| **Status** | {STATUS} (❌ NOT STARTED / 🔄 PARTIAL / ✅ COMPLETE) |
| **Complexity** | {COMPLEXITY} (XS/S/M/L/XL) |
| **Task Types** | {TASK_TYPES} (see below for what each type means) |

**Task Type → Required Tools:**
- `[SECURITY-CRITICAL]` → semgrep MCP + security-expert agent
- `[DATABASE]` → prisma-local MCP + database-expert skill + database agent
- `[API]` → api-builder agent + api-doc-generator skill
- `[UI]` → ui-ux-specialist + frontend-architect
- `[AUTHENTICATION]` → authentication-specialist + semgrep MCP
- `[INFRASTRUCTURE]` → devops-engineer + deployment skill
- `[TESTING]` → test-automation-engineer
- `[DOCUMENTATION]` → api-documentation-specialist
- `[WORKER]` → background-jobs-specialist
- `[VALIDATION]` → validation-expert + semgrep MCP

---

## What This Task Does

**Objective:** {CLEAR_DESCRIPTION_OF_WHAT_THIS_TASK_ACCOMPLISHES}

**Why it matters:** {EXPLANATION_OF_BUSINESS_VALUE_AND_TECHNICAL_IMPORTANCE}

**Done means:** {CLEAR_CRITERIA_FOR_WHEN_THIS_TASK_IS_CONSIDERED_COMPLETE}

---

## Required Tools (Non-Negotiable)

### Always Use These:

**MCPs:**
- ✅ **memory** - Check for past decisions at start, store new ones at end
  - Query: `search_nodes("{TASK_ID} {TASK_NAME}")`
- ✅ **sequential-thinking** - For architecture decisions and planning
- ✅ **Ref** - Research {TECHNOLOGIES_TO_RESEARCH}
- ✅ **context7** - Verify {FRAMEWORK_PATTERNS_TO_VERIFY}

**Skills:**
- ✅ **{PROJECT_DEV_SKILL}** - MUST invoke before any code work

### This Task Also Needs:

**MCPs:**
{LIST_TASK_SPECIFIC_MCPS}

Example:
- ✅ **prisma-local** - Use migrate-dev and migrate-status commands
- ✅ **semgrep** - Scan after any security-critical changes

**Skills:**
{LIST_TASK_SPECIFIC_SKILLS}

Example:
- ✅ **database-expert** - Invoke when modifying Prisma schema
- ✅ **api-doc-generator** - Invoke when creating new endpoints

**Sub-Agents:**
{LIST_TASK_SPECIFIC_AGENTS}

Example:
- ✅ **prisma-supabase-rls-expert** - For schema changes and RLS policies
- ✅ **trpc-api-builder** - For type-safe API endpoints

### Workflow

**BEFORE you start:**
1. Query memory MCP for past decisions
2. Invoke {PROJECT_DEV_SKILL} skill
3. Research with Ref/context7 MCPs
4. {TASK_SPECIFIC_PREPARATION}

**WHILE working:**
1. {TASK_SPECIFIC_DURING_STEP_1}
2. {TASK_SPECIFIC_DURING_STEP_2}
3. {TASK_SPECIFIC_DURING_STEP_3}

**AFTER you finish:**
1. {TASK_SPECIFIC_POST_STEP_1}
2. {TASK_SPECIFIC_POST_STEP_2}
3. Store decisions in memory MCP
4. Update task tracking file to ✅ COMPLETE

---

## Task Dependencies

**Need these done first:**
{LIST_OF_PREREQUISITE_TASK_IDS_AND_WHY}

Example:
- Task 0.2.1: PostgreSQL Setup - provides the database connection
- Task 0.1.3: Repository Structure - file structure must exist

**These are blocked until this is done:**
{LIST_OF_TASKS_THAT_CANNOT_START_UNTIL_THIS_IS_DONE}

Example:
- Task 1.2.1: User CRUD - needs database schema from this task
- Task 1.3.2: Rate Limiting - needs Redis connection

**Related work:**
{LIST_OF_RELATED_TASKS}

Example:
- Task 0.3.1: Authentication - shares database connection
- Task 0.4.2: Logging - use the patterns from there

**Can work on these in parallel:**
{PARALLEL_TASKS}

Example:
- Task 0.2.3: Typesense Setup
- Task 0.5.1: Documentation Framework

---

## Acceptance Criteria

**Task is COMPLETE when all of these are checked:**

{COPY_ACCEPTANCE_CRITERIA_FROM_TASK_TRACKING_FILE}

Example:
- [ ] Redis Docker container configured
- [ ] Client initialized in shared package
- [ ] Health check implemented
- [ ] Error handling for failures
- [ ] Tests passing
- [ ] Documentation updated

**Quality gates:**
- [ ] All criteria above checked off
- [ ] Code follows project patterns
- [ ] {TASK_SPECIFIC_QUALITY_GATE_1}
- [ ] {TASK_SPECIFIC_QUALITY_GATE_2}

Example quality gates:
- [ ] TypeScript compiles with no errors
- [ ] All tests pass
- [ ] Semgrep scan clean (for security tasks)
- [ ] Migrations run successfully (for database tasks)

---

## Implementation Guide

**Recommended approach:**
{STEP_BY_STEP_APPROACH}

Example:
1. Set up Docker config
2. Create client wrapper
3. Add error handling
4. Write tests

**Code patterns to follow:**
{SPECIFIC_PATTERNS}

Example:
```typescript
// ✅ Good
import { redis } from '@project/shared/lib/redis';
await redis.set('key', 'value', { ex: 3600 });

// ❌ Bad - bypasses error handling
import Redis from 'ioredis';
const redis = new Redis();

File structure:

{DIRECTORY_STRUCTURE}

Key tech:
{TECH_LIST_WITH_DOCS_LINKS}

Example:

• Redis - https://redis.io/docs/
• Docker - https://docs.docker.com/
• TypeScript - https://www.typescriptlang.org/docs/

Common Mistakes

{TASK_SPECIFIC_PITFALLS}

For DATABASE tasks:

• ❌ Running migrations without backups
• ❌ Not testing rollbacks
• ❌ Forgetting seed data
• ❌ Skipping RLS validation

For SECURITY tasks:

• ❌ Skipping semgrep scan
• ❌ Hardcoding secrets
• ❌ Not validating input
• ❌ Missing auth checks

General stuff to avoid:

• ❌ Skipping input validation
• ❌ Direct database access (use DAL)
• ❌ Missing auth checks
• ❌ Logging sensitive data
• ❌ Generic error messages
• ❌ Skipping audit logs

Files

Will create/modify:
{FILE_LIST}

Example:

• shared/src/lib/redis.ts - new
• docker-compose.yml - modified
• .env.example - modified

Documentation to update:
{DOCS_TO_UPDATE}

Example:

• docs/INFRASTRUCTURE.md
• docs/DEVELOPMENT.md
• README.md

Tests:
{TEST_FILES}

Example:

• shared/src/lib/redis.test.ts
• Manual: Docker health check

Verification

How to verify it's done:

1. {VERIFICATION_STEP_1}
2. {VERIFICATION_STEP_2}
3. {VERIFICATION_STEP_3}

Example:

# Check Docker
docker compose ps

# Run tests
pnpm --filter @project/shared test

# Check health endpoint
curl http://localhost:3000/api/health/redis

Commands to run:

{BUILD_COMMAND}
{TYPE_CHECK_COMMAND}
{TEST_COMMAND}
{LINT_COMMAND}

Security checks (if [SECURITY-CRITICAL]):

{SEMGREP_SCAN_COMMAND}

Reference Docs

• Claude config: instructions.md

Project docs:
{PROJECT_SPECIFIC_DOCS}

Post-Completion Checklist

After finishing, do these in order:

• Run all verification commands
• {TASK_SPECIFIC_POST_STEP_1}
• {TASK_SPECIFIC_POST_STEP_2}
• Update task tracking file to ✅ COMPLETE
• Store decisions in memory MCP
• Update related docs (if needed)
• Run security scan (if [SECURITY-CRITICAL])
• Commit with descriptive message

Trigger Keywords

{COMMA_SEPARATED_KEYWORDS}

Example: Redis setup, Redis integration, cache config, Task 0.2.2

Task Map

WHAT NEEDS TO BE DONE FIRST:
├─ {TASK_ID_1}: {TASK_NAME_1}
│  └─ Provides: {WHAT_IT_PROVIDES}

THIS TASK: {TASK_ID}: {TASK_NAME}

WHAT THIS BLOCKS:
├─ {TASK_ID_3}: {TASK_NAME_3}
│  └─ Needs: {WHAT_THIS_ENABLES}

PARALLEL WORK: {TASK_ID_5}, {TASK_ID_6}

INTEGRATION POINTS: {SYSTEM_1}, {SYSTEM_2}

Additional Context

{TASK_SPECIFIC_CONTEXT}

Example:

• Tech decisions: Using ioredis for better TypeScript support
• Performance: Connection pooling, 1hr TTL, graceful degradation
• Security: Password required in prod, no unencrypted sensitive data