Claude Tasks Workflow

A structured development workflow system that transforms Claude into a context-aware, self-improving development engine with specialized agents, persistent memory, and scalable orchestration.

Why Use This Workflow?

Using Claude directly for development means starting from scratch every time — no memory of your tech stack, inconsistent analysis quality, and manual tracking of everything.

This workflow fixes that:

• Specialized AI Agents — 5 agents, each optimized for a specific workflow phase (analysis, planning, implementation, updates, communication)
• Self-Improving — Captures lessons from corrections in real-time, reviews them before every task
• Lean Agents, Smart Commands — Agents investigate and return structured findings; commands own file output and documentation. This preserves agent context for the actual work
• Signals — Agents surface cross-repo dependencies, external blockers, design decisions, and developer input needs as informational findings. No automatic gates — the developer decides the response
• Autonomous Bug Fixing — Single-command fix pipeline for bugs and CI failures
• Adaptive Re-Planning — Agents stop and pivot when plans fail instead of pushing through
• Delta Updates — Change requirements mid-task without losing existing work (60-80% token savings)
• Team-Ready Architecture — Designed to scale from single-agent to agent teams when Claude Code agent teams stabilize

Quick Start

Installation

Copy the .claude/ folder to your project root:

git clone https://github.com/vik407/claude-tasks-workflow
cp -r claude-tasks-workflow/.claude /your/project/

Cursor plugin (cursor-task-workflow)

From a clone of this repository, build the Cursor plugin bundle (rules, skills, agents, commands, hooks):

npm install
npm run build:cursor-plugin
npm run validate:cursor-plugin

Optional release zip: npm run dist:cursor-plugin (writes build/dist/<date>/cursor-task-workflow.zip). Full runbook: docs/CURSOR_PLUGIN_MIGRATION_AND_DISTRIBUTION.md.

Your First Task

# Set up project context — run once per project
/project:context:init

# Initialize — creates task workspace with project context
/project:task:init TICKET-123

# Review analysis.md (check signals), then plan
/project:task:plan TICKET-123

# Implement — autonomous or guided
/project:task:implement TICKET-123 AUTO

Quick Fix (No Ceremony)

/project:task:fix BUG-456 "login form throws 500 error on invalid email"

Simple Change

/project:task:simple UI-202 "change submit button text from 'Send' to 'Submit'"

Architecture

Agent-Command Contract

Agents and commands have a strict separation of concerns:

Agent: investigate / plan / implement → return structured findings
Command: receive findings → write artifacts → manage files

Downstream commands always read the root artifact (analysis.md, plan.md, validation.md)

No agent writes documentation files. Commands own the output format. This keeps agent context available for the actual work rather than consumed by documentation generation.

Signals

Agents surface signals when they detect conditions that may affect the task:

Signal	Meaning
Cross-repo	Changes needed in other repositories or submodules
External dependency	Requires input, API, or action from another team or third party
Design decision	Multiple viable approaches — developer should choose
Blocker risk	Something outside the developer's control that could stall progress
Developer input needed	A validation, manual test, or question only the developer can answer

Signals are informational — they don't stop the workflow. The developer reads them in analysis.md or plan.md and decides: proceed, coordinate externally, or escalate.

Complexity Classification

Every task is classified using objective signals (not time estimates):

• SIMPLE — all must be true: ≤ 4 files, single component, ≤ 3 acceptance criteria, zero cross-service integration, existing pattern, no security/auth/migration risk
• COMPLEX — any one sufficient: ≥ 5 files or multiple components, cross-service changes, no existing pattern, security/auth/migration/performance risk
• Tiebreaker: default to COMPLEX. False COMPLEX costs one planning step. False SIMPLE risks production incidents

See shared/agent-guidelines.md for the full criteria, escalation protocols, and signal-driven escalation.

Parallel Work Folders

When investigation or validation benefits from parallel work (team analysis, multi-layer tasks), optional folders store per-domain findings:

.claude/tasks/TASK-ID/
├── analysis.md              # Always present — synthesized root file
├── analysis/                # Optional — per-domain findings
│   ├── backend.md
│   ├── frontend.md
│   └── integration.md
├── plan.md
├── validation.md            # Always present — synthesized root file
├── validation/              # Optional — per-domain results
│   ├── backend.md
│   └── e2e.md
└── debugging/               # Investigation artifacts

Folder files use descriptive names by domain, layer, or hypothesis. Downstream commands always read the root file, never the folder. Only create folders when parallel findings genuinely exist.

Commands Reference

Task Lifecycle

Command	Purpose
/project:task:init TASK-ID	Initialize task workspace with project context discovery
/project:task:analyze TASK-ID	Phase 1: Root cause analysis with signals
/project:task:plan TASK-ID	Phase 2: Implementation plan with checklist and signals
/project:task:implement TASK-ID MODE	Phase 3: Execute implementation (AUTO or GUIDED)
/project:task:fix TASK-ID "description"	Autonomous end-to-end bug fix
/project:task:simple TASK-ID "description"	Streamlined workflow for trivial changes

Task Management

Command	Purpose
/project:task:update TASK-ID "what changed"	Delta update without starting over
/project:task:status TASK-ID	Status report with unresolved signals
/project:task:status-change TASK-ID	Change status with stakeholder notification
/project:task:backlog TASK-ID	Return to backlog with unresolved signals documented
/project:task:cancel TASK-ID	Cancel with knowledge preservation
/project:task:reject TASK-ID	Reject plan with analysis

Context, Knowledge & Docs

Command	Purpose
/project:context:init	Initialize or validate CLAUDE.md (first step)
/project:context:refresh SECTION	Selective context refresh
/project:knowledge:extract TASK-ID	Extract patterns from completed task
/project:docs:update	Update project documentation
/project:docs:archive TASK-ID	Archive task with knowledge preservation

Workflow & Integration

Command	Purpose
/project:workflow:gate-check TASK-ID	Phase validation and compliance check
/project:workflow:handoff TASK-ID	Task handoff with zero context loss
/project:workflow:dev-handoff TASK-ID	Developer-specific technical handoff
/project:workflow:emergency TASK-ID	Emergency workflow override
/project:workflow:stakeholder-notify TASK-ID	Audience-specific notifications
/project:ci:validate TASK-ID	CI/CD validation with quality gates
/project:sprint:planning	Sprint planning readiness assessment
/project:jira:update TASK-ID	Jira ticket update
/project:meeting:brief TYPE TASK-ID	Meeting briefing (standup, tech-review, code-walkthrough, all)
/project:docs:meeting-prep TASK-ID	Meeting prep with documentation validation

Agents

Agent	Role	Writes files?
task-analyzer	Root cause investigation. Classifies complexity, surfaces signals, returns structured findings	No
task-planner	Solution architecture aligned with project patterns. Returns phased plan with checklist and signals	No
implementation-guide	Executes plans in AUTO or GUIDED mode. Stops and re-plans on unexpected issues	Yes (code + validation)
task-updater	Delta updates when requirements change. Preserves existing work, re-executes only affected phases	Yes (modifies existing artifacts)
meeting-facilitator	Audience-appropriate briefings — technical depth for engineers, business impact for PMs, strategic overview for executives	Yes (communication docs)

Agent Design Principles

• Lean prompts — agents focus on their job, not documentation formatting
• Explicit warm-up — every agent reads agent-guidelines.md and lessons.md on first invocation (subagents don't inherit parent context)
• Structured Return Format — each agent returns a defined set of findings; the calling command decides what to write
• Signals over gates — agents report what they find, never stop the workflow based on predictions

How It Works

Self-Improvement Loop

1. Lessons Capture — When you correct any agent, it records the lesson in tasks/lessons.md
2. Session Warm-Up — Before starting, agents read accumulated lessons to avoid repeating mistakes
3. Knowledge Extraction — After completion, architectural patterns go to project-patterns.md

Debugging Artifacts

Debug scripts, reproduction steps, log captures, and test harnesses created during investigation are saved to .claude/tasks/[TASK-ID]/debugging/. This preserves the investigative trail so peers can understand how root causes were discovered.

Adaptive Re-Planning

Agents recognize when a plan is failing and pivot: 2+ unexpected issues, broken assumptions, or design-level test failures trigger an immediate stop. The agent documents what went wrong and presents options instead of pushing through.

Signal-Driven Escalation

When analysis surfaces signals (cross-repo, external, blockers), the developer owns the response:

• No signals — proceed through normal flow
• Design decision — developer makes the call, flow continues
• Developer input — developer validates or answers, flow continues
• Cross-repo / blocker — developer decides: proceed with assumptions, coordinate externally, or escalate to team analysis

Team Analysis (Future — Agent Teams)

When Claude Code agent teams graduate from experimental, the workflow is designed to scale:

• Team analysis activates as an escalation from single-agent analysis, not a replacement
• analysis-lead coordinates: distributes competing hypotheses, challenges teammate findings, synthesizes results
• Investigators are the existing task-analyzer scoped to one hypothesis each
• Output contract is identical — analyze.md command receives the same Return Format whether from one agent or a team
• Parallel work folders (analysis/, validation/) store per-domain findings; the synthesized root file is always the source of truth

See docs/TEAM-ANALYSIS-ARCHITECTURE.md for the full design.

Repository Structure

claude-tasks-workflow/
├── src/claude/                  # Source templates (edit these)
│   ├── agents/                  # 5 specialized AI agents
│   ├── commands/project/        # Workflow commands by domain
│   ├── shared/                  # Shared principles (agent-guidelines.md)
│   ├── skills/                  # Enhanced commands with templates
│   └── tasks/lessons.md         # Behavioral corrections template
│
├── .claude/                     # Active workspace (deployed from src/)
│   ├── agents/                  # Deployed agents
│   ├── commands/                # Deployed commands
│   ├── shared/                  # Deployed shared guidelines
│   ├── tasks/                   # Task workspaces
│   │   ├── [TASK-ID]/           # Per-task docs + optional analysis/ validation/ folders
│   │   └── archive/             # Completed tasks
│   └── knowledge/               # Accumulated project patterns
│
├── scripts/                     # Build tooling (build, deploy, validate)
└── docs/                        # Architecture docs and guides

Directory	Purpose
src/claude/	Source templates — edit these to customize the workflow
.claude/	Active workspace — deployed from source, used by Claude Code
scripts/	Build pipeline: npm run build && npm run deploy

Contributing

We welcome contributions:

• Agent Prompts — Improve clarity, optimize token usage
• New Commands — Follow established patterns, include documentation
• Token Efficiency — Reduce redundancy across agents and commands (see below)

Submit issues and pull requests on GitHub.

Token Efficiency — Next Iteration

Areas identified for token savings in a future pass:

Warm-up duplication

All agents repeat the same core warm-up (read agent-guidelines + lessons.md). Options:

• A) Skills injection: Register agent-guidelines.md as a skill, use the skills: frontmatter field to auto-inject it. Removes the warm-up read step entirely — the guidelines arrive in the agent's context at startup. Saves tool calls and tokens per invocation
• B) Conditional warm-up: Move warm-up instructions to agent-guidelines only. Agents reference "follow warm-up in guidelines" instead of repeating the steps. Saves ~8 lines per agent but adds one read step

Phase gate duplication

analyze.md and plan.md commands repeat phase gate criteria from agent-guidelines. Replace with: "See Phase Gates in agent-guidelines." Saves ~5 lines per command but requires the agent (which reads guidelines during warm-up) to enforce gates rather than the command re-stating them.

SIMPLE/COMPLEX re-explanation in task-planner

task-planner re-explains SIMPLE/COMPLEX with implementation-specific context ("single-phase vs multi-phase"). This adds value beyond the guidelines definition — keep it but could compress to 2 lines:

SIMPLE → single-phase, existing patterns. COMPLEX → multi-phase, proof-of-concept first.

Estimated savings

Optimization	Lines saved	Token impact	Risk
Skills injection for guidelines	~50 across agents	Medium — removes 5 file reads per task	Depends on skills: frontmatter working reliably
Phase gate references	~10 across commands	Low	Enforcement moves to agent
Planner compression	~4	Minimal	None
Total	~64 lines	~5-10% per agent invocation	Low overall

The skills injection approach (option A) is the highest-value change — it eliminates the most common tool call across all agents while providing the guidelines content more reliably than a runtime file read.

License

Apache 2 License — See LICENSE file for details

---

Version: 5.2.0 Compatibility: Claude Code v2.1.x, Claude Sonnet 4.6, Claude Opus 4.6