everything-claude-code/.kiro/docs/longform-guide.md

Agentic Workflows: A Deep Dive

Introduction

This guide explores the philosophy and practice of agentic workflows—a development methodology where AI agents become active collaborators in the software development process. Rather than treating AI as a code completion tool, agentic workflows position AI as a thinking partner that can plan, execute, review, and iterate on complex tasks.

What Are Agentic Workflows?

Agentic workflows represent a fundamental shift in how we approach software development with AI assistance. Instead of asking an AI to "write this function" or "fix this bug," agentic workflows involve:

1. Delegation of Intent: You describe what you want to achieve, not how to achieve it
2. Autonomous Execution: The agent plans and executes multi-step tasks independently
3. Iterative Refinement: The agent reviews its own work and improves it
4. Context Awareness: The agent maintains understanding across conversations and files
5. Tool Usage: The agent uses development tools (linters, tests, formatters) to validate its work

Core Principles

1. Agents as Specialists

Rather than one general-purpose agent, agentic workflows use specialized agents for different tasks:

• Planner: Breaks down complex features into actionable tasks
• Code Reviewer: Analyzes code for quality, security, and best practices
• TDD Guide: Leads test-driven development workflows
• Security Reviewer: Focuses exclusively on security concerns
• Architect: Designs system architecture and component interactions

Each agent has a specific model, tool set, and prompt optimized for its role.

2. Skills as Reusable Workflows

Skills are on-demand workflows that agents can invoke for specific tasks:

• TDD Workflow: Red-green-refactor cycle with property-based testing
• Security Review: Comprehensive security audit checklist
• Verification Loop: Continuous validation and improvement cycle
• API Design: RESTful API design patterns and best practices

Skills provide structured guidance for complex, multi-step processes.

3. Steering Files as Persistent Context

Steering files inject rules and patterns into every conversation:

• Auto-inclusion: Always-on rules (coding style, security, testing)
• File-match: Conditional rules based on file type (TypeScript patterns for .ts files)
• Manual: Context modes you invoke explicitly (dev-mode, review-mode)

This ensures consistency without repeating instructions.

4. Hooks as Automation

Hooks trigger actions automatically based on events:

• File Events: Run type checks when you save TypeScript files
• Tool Events: Review code before git push, check for console.log statements
• Agent Events: Summarize sessions, extract patterns for future use

Hooks create a safety net and capture knowledge automatically.

Workflow Patterns

Pattern 1: Feature Development with TDD

1. Invoke planner agent: "Plan a user authentication feature"
   → Agent creates task breakdown with acceptance criteria

2. Invoke tdd-guide agent with tdd-workflow skill
   → Agent writes failing tests first
   → Agent implements minimal code to pass tests
   → Agent refactors for quality

3. Hooks trigger automatically:
   → typecheck-on-edit runs after each file save
   → code-review-on-write provides feedback after implementation
   → quality-gate runs before commit

4. Invoke code-reviewer agent for final review
   → Agent checks for edge cases, error handling, documentation

Pattern 2: Security-First Development

1. Enable security-review skill for the session
   → Security patterns loaded into context

2. Invoke security-reviewer agent: "Review authentication implementation"
   → Agent checks for common vulnerabilities
   → Agent validates input sanitization
   → Agent reviews cryptographic usage

3. git-push-review hook triggers before push
   → Agent performs final security check
   → Agent blocks push if critical issues found

4. Update lessons-learned.md with security patterns
   → extract-patterns hook suggests additions

Pattern 3: Refactoring Legacy Code

1. Invoke architect agent: "Analyze this module's architecture"
   → Agent identifies coupling, cohesion issues
   → Agent suggests refactoring strategy

2. Invoke refactor-cleaner agent with verification-loop skill
   → Agent refactors incrementally
   → Agent runs tests after each change
   → Agent validates behavior preservation

3. Invoke code-reviewer agent for quality check
   → Agent ensures code quality improved
   → Agent verifies documentation updated

Pattern 4: Bug Investigation and Fix

1. Invoke planner agent: "Investigate why login fails on mobile"
   → Agent creates investigation plan
   → Agent identifies files to examine

2. Invoke build-error-resolver agent
   → Agent reproduces the bug
   → Agent writes failing test
   → Agent implements fix
   → Agent validates fix with tests

3. Invoke security-reviewer agent
   → Agent ensures fix doesn't introduce vulnerabilities

4. doc-updater agent updates documentation
   → Agent adds troubleshooting notes
   → Agent updates changelog

Advanced Techniques

Technique 1: Continuous Learning with Lessons Learned

The lessons-learned.md steering file acts as your project's evolving knowledge base:

---
inclusion: auto
description: Project-specific patterns and decisions
---

## Project-Specific Patterns

### Authentication Flow
- Always use JWT with 15-minute expiry
- Refresh tokens stored in httpOnly cookies
- Rate limit: 5 attempts per minute per IP

### Error Handling
- Use Result<T, E> pattern for expected errors
- Log errors with correlation IDs
- Never expose stack traces to clients

The extract-patterns hook automatically suggests additions after each session.

Technique 2: Context Modes for Different Tasks

Use manual steering files to switch contexts:

# Development mode: Focus on speed and iteration
#dev-mode

# Review mode: Focus on quality and security
#review-mode

# Research mode: Focus on exploration and learning
#research-mode

Each mode loads different rules and priorities.

Technique 3: Agent Chaining

Chain specialized agents for complex workflows:

planner → architect → tdd-guide → security-reviewer → doc-updater

Each agent builds on the previous agent's work, creating a pipeline.

Technique 4: Property-Based Testing Integration

Use the TDD workflow skill with property-based testing:

1. Define correctness properties (not just examples)
2. Agent generates property tests with fast-check
3. Agent runs 100+ iterations to find edge cases
4. Agent fixes issues discovered by properties
5. Agent documents properties in code comments

This catches bugs that example-based tests miss.

Best Practices

1. Start with Planning

Always begin complex features with the planner agent. A good plan saves hours of rework.

2. Use the Right Agent for the Job

Don't use a general agent when a specialist exists. The security-reviewer agent will catch vulnerabilities that a general agent might miss.

3. Enable Relevant Hooks

Hooks provide automatic quality checks. Enable them early to catch issues immediately.

4. Maintain Lessons Learned

Update lessons-learned.md regularly. It becomes more valuable over time as it captures your project's unique patterns.

5. Review Agent Output

Agents are powerful but not infallible. Always review generated code, especially for security-critical components.

6. Iterate with Feedback

If an agent's output isn't quite right, provide specific feedback and let it iterate. Agents improve with clear guidance.

7. Use Skills for Complex Workflows

Don't try to describe a complex workflow in a single prompt. Use skills that encode best practices.

8. Combine Auto and Manual Steering

Use auto-inclusion for universal rules, file-match for language-specific patterns, and manual for context switching.

Common Pitfalls

Pitfall 1: Over-Prompting

Problem: Providing too much detail in prompts, micromanaging the agent.

Solution: Trust the agent to figure out implementation details. Focus on intent and constraints.

Pitfall 2: Ignoring Hooks

Problem: Disabling hooks because they "slow things down."

Solution: Hooks catch issues early when they're cheap to fix. The time saved far exceeds the overhead.

Pitfall 3: Not Using Specialized Agents

Problem: Using the default agent for everything.

Solution: Swap to specialized agents for their domains. They have optimized prompts and tool sets.

Pitfall 4: Forgetting to Update Lessons Learned

Problem: Repeating the same explanations to agents in every session.

Solution: Capture patterns in lessons-learned.md once, and agents will remember forever.

Pitfall 5: Skipping Tests

Problem: Asking agents to "just write the code" without tests.

Solution: Use the TDD workflow. Tests document behavior and catch regressions.

Measuring Success

Metrics to Track

1. Time to Feature: How long from idea to production?
2. Bug Density: Bugs per 1000 lines of code
3. Review Cycles: How many iterations before merge?
4. Test Coverage: Percentage of code covered by tests
5. Security Issues: Vulnerabilities found in review vs. production

Expected Improvements

With mature agentic workflows, teams typically see:

• 40-60% reduction in time to feature
• 50-70% reduction in bug density
• 30-50% reduction in review cycles
• 80%+ test coverage (up from 40-60%)
• 90%+ reduction in security issues reaching production

Conclusion

Agentic workflows represent a paradigm shift in software development. By treating AI as a collaborative partner with specialized roles, persistent context, and automated quality checks, we can build software faster and with higher quality than ever before.

The key is to embrace the methodology fully: use specialized agents, leverage skills for complex workflows, maintain steering files for consistency, and enable hooks for automation. Start small with one agent or skill, experience the benefits, and gradually expand your agentic workflow toolkit.

The future of software development is collaborative, and agentic workflows are leading the way.