.kiro/docs/longform-guide.md
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.
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:
Rather than one general-purpose agent, agentic workflows use specialized agents for different tasks:
Each agent has a specific model, tool set, and prompt optimized for its role.
Skills are on-demand workflows that agents can invoke for specific tasks:
Skills provide structured guidance for complex, multi-step processes.
Steering files inject rules and patterns into every conversation:
This ensures consistency without repeating instructions.
Hooks trigger actions automatically based on events:
Hooks create a safety net and capture knowledge automatically.
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
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
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
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
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.
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.
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.
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.
Always begin complex features with the planner agent. A good plan saves hours of rework.
Don't use a general agent when a specialist exists. The security-reviewer agent will catch vulnerabilities that a general agent might miss.
Hooks provide automatic quality checks. Enable them early to catch issues immediately.
Update lessons-learned.md regularly. It becomes more valuable over time as it captures your project's unique patterns.
Agents are powerful but not infallible. Always review generated code, especially for security-critical components.
If an agent's output isn't quite right, provide specific feedback and let it iterate. Agents improve with clear guidance.
Don't try to describe a complex workflow in a single prompt. Use skills that encode best practices.
Use auto-inclusion for universal rules, file-match for language-specific patterns, and manual for context switching.
Problem: Providing too much detail in prompts, micromanaging the agent.
Solution: Trust the agent to figure out implementation details. Focus on intent and constraints.
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.
Problem: Using the default agent for everything.
Solution: Swap to specialized agents for their domains. They have optimized prompts and tool sets.
Problem: Repeating the same explanations to agents in every session.
Solution: Capture patterns in lessons-learned.md once, and agents will remember forever.
Problem: Asking agents to "just write the code" without tests.
Solution: Use the TDD workflow. Tests document behavior and catch regressions.
With mature agentic workflows, teams typically see:
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.